// agents.troubleshooting

Troubleshooting

When the bridge spins but no tools show up — or when a tool call comes back angry — this is the checklist.

Error codes

Every failed request carries a JSON-RPC error object and the HTTP status below. The error.message field is always human-readable; use error.code for programmatic branching.

HTTP	Code	Fix
401	`unauthorized`	Key missing, mistyped, or revoked. Check for stray whitespace on paste; rotate via Profile → API Keys if in doubt.
403	`out_of_scope`	Key is valid but lacks the scope the tool needs. Either widen the persona on the existing key, or issue a second key with the right scopes and switch the agent to it.
403	`tenant_mcp_disabled`	The MCP surface isn't enabled on your plan yet. Contact support to upgrade.
429	`slow_down`	Rate limit hit. Back off with exponential jitter, reduce parallel tool calls, or ask for a higher ceiling via support.
5xx	`server_error`	Transient in 99% of cases. Retry once with a 1-2s delay. If it persists, check status.boardherald.com and file an issue with the request-id from the response header.

Claude Desktop — "Server disconnected"

Almost always a bridge spawn problem rather than an auth issue. Check in this order:

node --version — must be 18 or newer. Claude Desktop picks up your login-shell PATH; verify with which node from the same shell.
Absolute path to node in the config if PATH resolution is unreliable (e.g. /usr/local/bin/node on macOS, or C:\Program Files\nodejs\node.exe on Windows).
Valid JSON in claude_desktop_config.json. Paste into a validator if you hand-edited — the file is silently ignored if malformed.
Quit Claude Desktop fully (dock icon, not just the window) before restarting. The stdio connection is established at launch.

"Connected" but tools don't appear

MCP tools are loaded on the first tool-requiring prompt, not eagerly. Start a new conversation and ask something like "what BoardHerald tools do you have access to?" — the model will call tools/list and the catalogue will show up in the UI.

Existing conversations cache an empty tool list if they started before the server connected. A new thread fixes it.

Watch out for smart quotes

Copy-pasting config snippets through a chat client (Slack, WhatsApp, some email) can convert straight " into curly “. JSON parsers reject that. If Claude Desktop logs Could not load app settings, open the file in a plain text editor and verify the quotes.

When it's actually a BoardHerald outage

Check status (page forthcoming — Phase 3) and the release workflow status on GitHub. If the server is genuinely down, retries won't help.

Something we haven't covered?

Open an issue at github.com/getbananalabs/boardherald-mcp/issues. Include:

Bridge version (npx @boardherald/mcp-bridge --version).
MCP client + version (Claude Desktop 1.x, ChatGPT, custom).
Node version (node --version).
The stderr log from the bridge (no API keys, please).
If present, the request-id / x-request-id header from any 5xx response.