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 > MCP Servers
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

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.ai

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