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

OAuth fails with redirect_uri must use a loopback address or custom URI scheme

This is what you hit when your OAuth client runs on your own domain — a server-side web app, or any other headless integration — rather than inside a desktop MCP client. Every redirect URI is checked against an allowlist of origins: loopback addresses, custom URI schemes, and known MCP client origins. Your own hostname is not on it yet, so the request is rejected before the consent screen.

• Re-registering will not help. Dynamic client registration accepts your https callback, issues a client_secret, and echoes the URI back — but nothing it returns is read when the redirect is checked. A fresh client_id, or one pre-issued to you, changes nothing. Only the origin is gated.
• Your PKCE setup is fine. code_challenge and code_challenge_method are forwarded untouched and the verifier never passes through us, so nothing about an S256 flow needs to change.
• If you only need read tools, skip OAuth entirely. teams_list, models_list and usage all work with Authorization: Basic base64(KEY:SECRET) using a team API key — no redirect, no allowlist.
• Team-level writes do need per-user OAuth. Team-level model access updates are refused to API keys at any scope, and the signed-in user must be a team Admin rather than a Member. A Member's write fails with a permission error that does not look obviously different from this one.
• To have your origin allowlisted, contact support with: the bare https origin (https://host, plus the port if you use one, and no path — the allowlist is origin-level, so your callback path can move later), whether you need it on production or a preview environment, and the tools you plan to call.

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://preview.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 preview.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 — 57 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 86 tools individually, no catalog lookup required: