> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/agent-bridge/troubleshooting.md).

# Troubleshooting

Fix common Agent Bridge problems such as 401 errors, queued calls, no boards found, missing tools and stale credentials

## Goal

Get an external agent working again when its Protoboard calls fail.

## Start here

Ask your agent to call `get_bridge_diagnostics`. It reports whether the board's tab is alive and listening. Then find your symptom below.

<details>

<summary>401, "Unauthorized" or "Not authenticated"</summary>

The key is wrong, revoked or sent without `Bearer` . Check that the header is exactly `Authorization: Bearer pb_agent_…`, that the key isn't revoked in **Settings > Developer**, and that any environment variable your config uses is set where the client runs. If you lost the key, create a new one.

</details>

<details>

<summary>"No board connected" or no boards found</summary>

No board is open in a signed-in browser tab for the same account as the key. Open the board (or ask the agent to use `open_board` and open the link it returns), then retry.

</details>

<details>

<summary>"Multiple boards open - use connect_board to pick one"</summary>

The agent hasn't picked a board yet. Ask it to call `connect_board` with the board you want.

</details>

<details>

<summary>A call comes back QUEUED</summary>

The board's tab is asleep: the browser throttles background tabs. This isn't a failure. Click the tab to wake it and the queued calls run. The agent can check a call with `get_call_status` and its `callId`.

</details>

<details>

<summary>"The connected board ... no longer has an open browser tab"</summary>

The tab for the connected board was closed. The connection doesn't switch boards on its own. Reopen the board, or have the agent call `connect_board` for another open board.

</details>

<details>

<summary>A call timed out</summary>

The tab didn't answer in time, often during a very large operation. Check the result with `get_call_status`, then retry if needed. Refreshing a frozen tab re-registers it.

</details>

<details>

<summary>The client connects but shows no Protoboard tools</summary>

The client hasn't refreshed its tool list. In VS Code, run **MCP: List Servers** and restart the server. In CLI clients, restart the client or rerun `/mcp`. In Claude Desktop, quit and reopen the app.

</details>

<details>

<summary>Auth errors continue after you changed the key</summary>

Some clients cache the connection. Remove the server and add it again, for example `claude mcp remove protoboard`, then rerun the add command. For `mcp-remote`, clearing `~/.mcp-auth` also helps.

</details>

<details>

<summary>Edits fail or don't save on a shared board</summary>

On a board shared with others, only the person holding editing control can change it. If the status pill in your browser says **Viewing**, click it and choose **Start editing**, then retry.

</details>

<details>

<summary>Running the agent in WSL with Protoboard in Windows</summary>

The hosted URL `https://alpha.protoboard.ai/api/mcp` works from both sides. Only the browser tab needs to be signed in to the same account as the key.

</details>

## Still stuck?

Send the output of `get_bridge_diagnostics` and your client name to the team. See [Get help](https://docs.protoboard.xyz/help/get-help.md).

## Related pages

* [Setup](https://docs.protoboard.xyz/agent-bridge/setup.md)
* [API keys](https://docs.protoboard.xyz/agent-bridge/api-keys.md)
* [Tool reference](https://docs.protoboard.xyz/agent-bridge/tool-reference.md)
