Authentication and troubleshooting

Authorization expired

BitBoard access tokens expire. If a previously working client can no longer connect, disconnect BitBoard in that client and authorize it again.

For Codex, run:

codex mcp login bitboard

Other clients reopen the authorization flow when you reconnect the BitBoard MCP server.

BitBoard does not appear in the client

Confirm that the client is configured with the remote MCP URL:

https://app.bitboard.work/mcp

Then restart or refresh the client’s MCP connections. See Connect your agent for the current configuration format.

A connected-app or repository tool is missing

Connection tools are dynamic. They appear only when:

• the connection belongs to the authenticated BitBoard account;
• authorization for that connection is healthy; and
• BitBoard can discover tools for it.

Check the connection under Settings → Connections, then refresh MCP discovery in your client.

A dashboard tool cannot find a dashboard

Dashboard tools respect BitBoard permissions. Confirm that the account used during MCP authorization can access the dashboard and that the dashboard ID came from list_dashboards or the dashboard URL.

A block body is missing from dashboard_get

This is expected. dashboard_get omits authored block source by default to keep reads small. Call dashboard_get_block_source for the block you need, or pass include_source: true when a full export is necessary.

A local file upload fails

Use dashboard_create_upload_url for files on the agent’s machine. Upload URLs are short-lived. Large files must use the chunked upload URL returned by the tool before calling dashboard_finalize_upload.