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

Most Scenario MCP tools require team and project context. When only one team and project are possible, the server fills them in for you and says so in its reply. Otherwise the error itself lists your teams and projects with their ids — no lookup call is needed.

• Pick a team and project from the list in the error, then pass team_id and project_id to the tool call
• Your AI agent should ask which workspace to use rather than pick one. If it picked silently, tell it to ask.
• teams_list and projects_list are still available if you want the full list at any time

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 model_schema_get 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 jobs_wait tool to wait for job completion (or job_get for a status snapshot)
• Set wait: false on model_run 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 upload_asset_complete 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 model_run?

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

The default connection only lists a lean core

By default the server advertises a 29-tool core covering the most common generation, asset, and workflow tasks. Every other tool — 56 of them — still exists on the server and is fully documented here; it just isn't in the default tools/list. Those tools are reachable through the tool catalog gateway:

• scenario_tools_list to enumerate every tool in the catalog
• scenario_tools_search to find a tool by name or description and get its schema
• scenario_tool_execute_read, scenario_tool_execute_write, or scenario_tool_execute_delete to run it, matching the tool's read/write/delete lane

Want every tool listed directly instead?

Append ?toolsets=full to your connection URL and reconnect — your client will then list all 85 tools individually, no catalog lookup required: