For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
- 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.
- 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.
- 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.
