Troubleshooting - Builder Studio Docs

Most connection problems with the /api/mcp gateway come down to the bearer token, the scopes on that token, the endpoint URL, or rate limiting. This page maps the common symptoms to causes and fixes. For setup details, see Dashboard setup and Client commands.

The tools never appear in my client

Restart the client after adding the server — tools are loaded at startup.
Confirm the URL is exactly https://builder.studio/api/mcp over Streamable HTTP, not a published-server path like /api/user-mcp/<workspaceId>/<slug>.
Confirm the Authorization header is present and formatted as Bearer builder_.... A missing or malformed header means no tools load.
Remember the tool list is scope-gated: a key may authenticate successfully but still show only the tools its scopes allow.

401 Invalid or expired token

The gateway could not verify the bearer token. The token is missing, malformed, revoked, or expired.

Check for typos and stray whitespace in the builder_ value.
Raw keys are shown only once. If you cannot find the original, revoke it and create a fresh key from Security → Workspace API Keys.
Confirm the key belongs to the workspace whose canvases you expect to see.

403 missing required scope

Authentication succeeded but the token lacks a scope the tool requires. The gateway returns a clear, per-tool scope error rather than a generic failure:

1Error: This bearer token is missing required scope. trigger_workflow accepts2'run:workflows'. Re-issue the workspace API key or OAuth grant with at least one3of those scopes enabled.

Fix it by re-issuing the key with the needed scope enabled. As a quick reference: read:canvases for inspection, run:workflows for running and inspecting executions, write:canvas for authoring, read:assets/write:assets for assets, read:billing for billing, manage:integrations for workspace/integration admin, and the delete:* scopes for permanent deletion. The full list is in Dashboard setup.

Scopes are fixed at issue time

You cannot add a scope to an existing key. To change what a connection can do, revoke the current key and create a new one with the correct scopes, then update your client config.

429 Too many requests

The gateway applies a best-effort rate limit per connection. When you exceed it, requests return 429 with a Retry-After header.

Have the agent back off and retry after the interval the response indicates.
Batch or reduce rapid polling loops — for example, poll execution status on an interval rather than in a tight loop.

403 origin / same-origin errors

For browser-originated requests (those that send an Origin or Referer header), the gateway enforces a same-origin / allowlist policy. Native MCP clients like Claude Code, Cursor, and Codex normally do not send these headers, so this rarely affects them. If you hit an origin error from a browser-based client, you are likely connecting from a host that is not on the allowed-origins list for OAuth connector flows.

The endpoint returns errors for a published server

If you are trying to reach a published user MCP server rather than the workspace gateway, the rules are different: those servers live at /api/user-mcp/<workspaceId>/<slug> and use a separate owner-managed credential path. Workspace builder_ keys do not unlock them. See Marketplace overview for that flow.

A fast end-to-end check

Ask the agent to call list_canvases. If it returns your canvases, the endpoint, token, and base scopes are all correct, and any remaining failure is almost certainly a per-tool scope issue rather than a connection problem.

Still stuck?

Review the authentication model in Authentication, re-check the connection commands in Client commands, and confirm the tool you want is in the Visual tool map.

Was this page helpful?