Troubleshooting

OAuth authentication fails

• Verify your Scenario account exists at app.scenario.com
• Ensure your client supports OAuth authentication
• Try reauthenticating using your client's MCP management flow (see below)

API key authentication fails

• Verify base64 encoding: echo -n 'KEY:SECRET' | base64
• Check credentials at app.scenario.com/team
• Ensure the Authorization header uses the format: Basic <base64>

Missing team_id or project_id error

OAuth users must provide team and project context for most tools. Your AI agent should discover these automatically. If it doesn't, ask your agent to:

1. Call list_teams to find your teams
2. (Optional when you have several teams / projects) Call list_projects using the returned team_id
3. Pass both team_id and project_id to subsequent tool calls

Reauthenticating in Claude Code

If your OAuth token has expired:

1. Type /mcp in the prompt
2. Select the Scenario server
3. Choose "Clear authentication" or "Authenticate"
4. Follow the browser-based OAuth prompts

Reauthenticating in Cursor

Cursor handles reconnection through its settings UI:

1. Open Settings > Tools & MCP
2. Find the Scenario server
3. Deactivate and reactivate the server
4. Complete the OAuth flow if prompted

Reauthenticating in VS Code

Remove and re-add the server to trigger a fresh OAuth flow:

1. Open Command Palette (Cmd+Shift+P)
2. Search "MCP: List Servers"
3. Find Scenario, remove and re-add using the config from the Installation page

Reauthenticating in Claude Desktop

Close the App and restart. If it doesn't work, remove and re-add the server, then restart:

1. Open Settings > Developer > Edit Config
2. Remove the Scenario entry
3. Re-add using the config from the Installation page
4. Restart Claude Desktop

Reauthenticating in OpenCode

Use the CLI to cycle your auth session:

1. Check status: opencode mcp auth list
2. Log out: opencode mcp logout scenario
3. Log back in: opencode mcp auth scenario

Claude Desktop reopens the browser on every message

An orphaned mcp-remote process might still be holding the connection port. Each new Claude Desktop session spawns a fresh mcp-remote that crashes with EADDRINUSE before the OAuth callback can be received, so Claude reopens the browser and the loop repeats.

1. Quit Claude Desktop (Cmd+Q — fully) and reboot your Mac. That kills any orphaned process holding the connection port.
2. If the prompt comes back after rebooting, the cached bridge state may be stale. Quit Claude Desktop, reboot once more, then in a terminal clear any remaining process and the cache before reopening Claude Desktop to sign in:
   pkill -f mcp-remote rm -rf ~/.mcp-auth

   Copy
3. Long-term fix: switch to Claude Desktop's native URL config — see the Installation page. No local process, no port conflicts.

Invalid model_id

• Use search or recommend to find valid model IDs
• Model IDs follow the model_ prefix format

Unsupported operation for model

• Call get_model_schema first to discover what a model supports
• Different models accept different parameters and operations

Timeout errors

• Generation can take 30-120s for video and 3D models
• Use the manage_jobs tool with action: check to check job status
• Set wait: false on run_model to get a job_id immediately

Cannot connect to MCP server

• Verify the URL: https://mcp.scenario.com/mcp
• Check your MCP client configuration syntax

Upload fails — file too large for inline upload

Files over 100KB should not be uploaded inline (base64 consumes context window). Use the presigned URL path instead:

1. Call upload_asset with file_size instead of data
2. Use curl to PUT each part to the returned presigned URLs
3. Call complete_upload with the returned upload_id

curl fails in Claude Desktop

Claude Desktop's sandbox blocks outbound requests by default.

• Go to Settings > Capabilities > Code execution > Additional allowed domains and add mcp.scenario.com
• Alternatively, upload the file at app.scenario.com and pass the resulting asset_id directly

Upload stuck at "validating"

• The file may be corrupted or in an unsupported format
• Verify that content_type matches the actual file format (e.g. image/png for a PNG file)

Upload token expired (410 Gone)

• Presigned URLs expire after 5 minutes
• Call upload_asset again to receive fresh presigned URLs

How do I use an uploaded file with run_model?

1. Upload with upload_asset to get an asset_id
2. Call get_model_schema to discover the parameter names the model accepts (e.g. image, referenceImages)
3. Pass the asset_id in the appropriate run_model parameter