Getting Started with the Scenario MCP Server

Last updated: April 9, 2026

The Scenario MCP (Model Context Protocol) server connects your AI coding agent directly to your Scenario workspace. Instead of switching between your IDE and the Scenario web app, you can generate images, train models, manage assets, and run workflows entirely from within your agent conversation - no manual API calls required.

What you get:

  • 17 tools covering image, video, 3D, and audio generation

  • Access to 344+ generative models in your workspace

  • Full pipeline from generation to asset management, all from your IDE

Prerequisites

Before you start, you'll need:

  1. A Scenario account - sign up at app.scenario.com

  2. An MCP-compatible client - see the Supported Tools section below

  3. Your API credentials (only if using API Key auth) - available at → Project API Keys tab

Authentication Methods

The Scenario MCP server supports two authentication methods.

OAuth is the simplest option — no credentials to copy or encode. Here's how the flow works:

  1. Set up your client using the instructions in the Installation section below (no credentials needed in the config)

  2. Make your first Scenario request — ask your agent anything like "List my Scenario teams"

  3. A browser window opens automatically, taking you to scenario.com

  4. Log in to your Scenario account (if not already logged in)

  5. Click Authorize to grant your client access to your workspace

  6. The browser confirms the connection — you can close it and return to your agent

  7. Your agent is now authenticated and ready to use all 17 Scenario tools

Tip: If you see a Forbidden error after a successful connection, your token may have expired. Go to your client's MCP settings, disconnect Scenario, then reconnect to trigger a fresh OAuth flow. If that doesn't work, clear the local OAuth cache with rm -rf ~/.mcp-auth and reconnect.

API Key

Use this method if your client doesn't support OAuth, or if you prefer static credentials.

  1. Go to app.scenario.com/team → Project API Keys tab

  2. Copy your API Key and API Secret

  3. Base64-encode them: echo -n 'YOUR_KEY:YOUR_SECRET' | base64

  4. Use the encoded string in your configuration (see setup examples below)

Important: Make sure your API key has write/generation permissions, not just read access. A read-only key will connect successfully but return Forbidden when you try to generate images or run models.

Supported Tools

The Scenario MCP server supports 11 AI coding platforms:

  • Claude Code: claude mcp add CLI command

  • Cursor 1.0+: JSON config or one-click install

  • VS Code: Settings UI or JSON config

  • Claude Desktop: npx mcp-remote

  • Windsurf: npx mcp-remote

  • Zed: npx mcp-remote

  • Warp: npx mcp-remote

  • Gemini CLI: Config file + /mcp auth

  • OpenCode: Config file + opencode mcp auth

  • Amp: Config file

  • Codex: Config file

Installation

Claude Code

With OAuth (Recommended):

  1. Open your terminal and run: claude mcp add --transport http scenario https://mcp.scenario.com/mcp

  2. Start a new Claude Code session

  3. Ask anything Scenario-related, for example: "List my Scenario teams"

  4. Claude Code will open a browser tab automatically for OAuth authorization

  5. Log in to Scenario and click Authorize

  6. Return to the terminal — you're connected

With API Key:

  1. Get your Base64-encoded credentials.

  2. Run: claude mcp add --transport http scenario https://mcp.scenario.com/mcp --header "Authorization: Basic YOUR_BASE64_ENCODED_KEY_SECRET"

Cursor 1.0+

Manual JSON config: Open or create ~/.cursor/mcp.json (applies to all projects) or .cursor/mcp.json at your project root:

JSON

{
  "mcpServers": {
    "scenario": {
      "url": "https://mcp.scenario.com/mcp"
    }
  }
}

VS Code

Option A — One-click install (OAuth):

  1. Visit mcp.scenario.com and select VS Code

  2. Click Install in VS Code — this opens VS Code via a deep link

  3. Confirm adding the server and authorize via the browser on your first request.

Claude Desktop, Windsurf, Zed, Warp

These use npx mcp-remote as a bridge. Example config for OAuth:

JSON

{
  "mcpServers": {
    "scenario": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.scenario.com/mcp"]
    }
  }
}

Available Tools

The Scenario MCP server exposes 17 tools including:

  • Discovery: list_teams, list_projects, search, recommend

  • Generation: run_model, get_model_schema

  • Assets: manage_assets, upload_asset, complete_upload, display_asset, analyze

  • Management: manage_models, train, manage_workflows

  • Jobs: manage_jobs, usage

Uploading Files

For files larger than 3MB, the MCP server uses a presigned S3 upload flow:

  1. Call upload_asset — returns presigned URLs.

  2. Your agent uploads the parts (handled automatically).

  3. Call complete_upload — returns an asset_id.

  4. Use asset_id in your next run_model call.

Troubleshooting

  • "Forbidden" error: Check if your API key has write/generation scope and your role is Editor or higher.

  • OAuth 401: Clear cache with rm -rf ~/.mcp-auth and reconnect.

  • Cursor "Allow?": Add an autoApprove array to your mcp.json with the tool names.