> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Troubleshooting

> Fix common BCTRL MCP connection and authentication issues.

* **Connection refused or no tools appear:** confirm the client points at `https://api.bctrl.ai/mcp` and supports remote Streamable HTTP MCP. If it only speaks stdio, use the [`mcp-remote` bridge](/mcp/transports).
* **Stuck on approval:** the browser device-approval flow must complete against the account that owns the API key. Re-run the client's login command — for Codex, `codex mcp login bctrl`.
* **403 or permission denied on a tool:** the approved API key lacks that scope. Approve a key with the needed scopes. See [Authentication](/mcp/auth).
* **Clear saved auth and retry:** remove the client's stored MCP token — for Codex, `codex mcp logout bctrl` — and reconnect.
* **The agent guesses a wrong request body:** have it call `bctrl_get_operation` and read `schemas://{schemaName}` before writing. Generated tools put JSON payloads under `body`, not at the top level.
* **A built-in Tool rejects its input:** call `bctrl_tools_get` with the Tool name, such as `stagehand.act`, and use the returned capability input schema.
* **A long operation stops after 60 seconds:** increase the MCP client's tool timeout. This is separate from `timeoutMs`, which only controls how long an SSE operation collects events.
* **Local dev returns metadata but no auth:** gateway-only local MCP covers catalog and bearer-token smoke tests; the full OAuth/device flow needs the complete local stack, because the gateway delegates approval to control-plane.