> 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-mcp/setup.md). # Setup Create an agent API key and connect Claude Code, Codex, or Gemini CLI to your live Protoboard session over HTTP Create an API key in Protoboard, drop a short config into your agent, and verify the connection. Any tier can create agent keys. ## Fast path: let your agent do the setup If your agent can fetch URLs (Claude Code, Codex, and Gemini CLI all can), paste this prompt. It reads this page and writes its own config, pausing only for the API key. ``` Set up the Protoboard MCP server globally for my user account (not project-scoped) so every session of this agent can use it. The instructions live at https://docs.protoboard.xyz/agent-bridge/setup.md, and a plain-text bundle of the whole docs site is at https://docs.protoboard.xyz/llms-full.txt. Follow the user-scope steps for whichever agent you are running right now (Claude Code, Codex, or Gemini CLI). Pause at the API-key step so I can create a key in Protoboard's Settings > Developer scoped specifically to you (label it something like ", ") and paste it back. Do not reuse an existing key, even if I have one: one key per agent keeps the audit log clean. Handle the rest yourself, including writing the config file in the right place. If I ask later for a project-scoped install instead, switch to the "Project scope alternative" block on that page. ``` Prefer doing it by hand? The manual steps follow. *** ## Step 1: Create an agent API key Open **Settings > Developer** inside Protoboard (profile menu, top right, then the **Developer** tab). ![Developer tab showing existing agent keys with rename and revoke controls](https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-f9bbfdac0b82f03a04ee2901014c277b235e6c08%2Fsettings-developer-overview.png?alt=media) Click **New agent key**, give it a label that says where it lives (for example, `Claude Code, work laptop`), and click **Create**. Create one key per agent rather than sharing a key, so you can revoke a single agent without disrupting the rest. Protoboard shows the full key **exactly once**. Copy it now. ![One-time reveal of a freshly created agent key, with a copy button](https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-4f7ce735d6d001282fa02e68a5dbd36b46ac1a97%2Fsettings-developer-key-created.png?alt=media) {% hint style="danger" %} **Treat the key like a password.** Anyone with it can run tools on your open boards. Never commit keys to version control; prefer an environment variable or your OS secret store. If you lose a key, revoke it and create a replacement. {% endhint %} *** ## Step 2: Configure your agent Each tab installs Protoboard at the user level, so it is available in every session of that agent. To share the config with a team through version control instead, see the "Project scope alternative" in each tab. {% tabs %} {% tab title="Claude Code" %} ```bash claude mcp add-json --scope user protoboard '{"type":"http","url":"https://alpha.protoboard.xyz/api/mcp","headers":{"Authorization":"Bearer pb_agent_YOUR_KEY_HERE"}}' ``` That writes this block into your user-level Claude Code config: ```json { "mcpServers": { "protoboard": { "type": "http", "url": "https://alpha.protoboard.xyz/api/mcp", "headers": { "Authorization": "Bearer pb_agent_YOUR_KEY_HERE" } } } } ``` Verify with `/mcp`: you should see `protoboard` as **Connected** with a tool count. For local Protoboard development, use `http://localhost:3000/api/mcp` instead.
Project scope alternative Drop the JSON block above into a `.mcp.json` file at the project root. Claude Code asks you to trust project-level MCP servers on first use. Replace the Bearer value with an env-style placeholder before committing.
{% endtab %} {% tab title="OpenAI Codex" %} Add the server to `~/.codex/config.toml`: ```toml [mcp_servers.protoboard] url = "https://alpha.protoboard.xyz/api/mcp" [mcp_servers.protoboard.http_headers] Authorization = "Bearer pb_agent_YOUR_KEY_HERE" ``` Newer Codex builds also accept `codex mcp add`. The token must come from an environment variable rather than a literal flag: ```bash export PROTOBOARD_AGENT_KEY=pb_agent_YOUR_KEY_HERE codex mcp add protoboard \ --url https://alpha.protoboard.xyz/api/mcp \ --bearer-token-env-var PROTOBOARD_AGENT_KEY ``` The CLI does not expose a flag for arbitrary headers; for those, use the `config.toml` block above. Confirm flags with `codex mcp add --help` and the [OpenAI Codex docs](https://developers.openai.com/codex).
Project scope alternative Drop the same TOML block into `.codex/config.toml` at your project root. Codex loads project config on top of user config; the project entry wins.
{% endtab %} {% tab title="Gemini CLI" %} Add the server to `~/.gemini/settings.json`: ```json { "mcpServers": { "protoboard": { "httpUrl": "https://alpha.protoboard.xyz/api/mcp", "headers": { "Authorization": "Bearer pb_agent_YOUR_KEY_HERE" } } } } ``` Or from the command line: ```bash gemini mcp add protoboard \ --httpUrl https://alpha.protoboard.xyz/api/mcp \ --header "Authorization: Bearer pb_agent_YOUR_KEY_HERE" ``` Verify with `/mcp list`. {% hint style="warning" %} **Use `protoboard` as the server name.** Gemini CLI namespaces tools as `mcp__`, so avoid underscores in the name itself. {% endhint %}
Project scope alternative Put the same JSON block into `.gemini/settings.json` at your project root. Gemini CLI merges project settings over user settings on conflict.
{% endtab %} {% tab title="Other clients" %} Any MCP client that can call an HTTPS endpoint works. Point it at `https://alpha.protoboard.xyz/api/mcp` with an `Authorization: Bearer pb_agent_YOUR_KEY_HERE` header, using the HTTP (Streamable HTTP) transport. Cursor, Windsurf, and Zed follow the standard MCP HTTP config shape used above. {% endtab %} {% endtabs %} *** ## Step 3: Verify the connection With your agent running and a Protoboard tab open, ask it: "What Protoboard boards do I have open?" You should get back a board name and ID. Within a second or two, a green **Agent** badge appears next to the board name in the Protoboard header. ![Agent badge visible in the Protoboard header breadcrumb](https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-d8e841ff24d1382c7bbeffd8a958e601127676f7%2Fagent-badge-connected.png?alt=media) Click the badge, or open the **Agents** tab in the left sidebar, to see each connected agent's key label, last activity, and the tool it is running now. ![Agents panel listing the connected agent alongside recently inactive ones](https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-6e0d251daaa51bd5785f78b77b7244e1559baa94%2Fagents-panel.png?alt=media) *** ## Working with boards and keys * **One board open:** the agent auto-connects. **Multiple boards:** ask your agent to run `list_boards`, then `connect_board` with the ID you want; every later call targets that board until you switch. * **Rename or revoke** keys from the Developer tab. Revocation takes effect on the next call. **Last used** updates on every call, so a stale timestamp is a good revocation candidate. * Revoking does not edit your agent config. Update the config to a new key so the agent stops retrying with a dead credential. *** ## Common failures
"Unauthorized" or 401 errors from the agent The Bearer token is wrong, missing, or revoked. Check that the key matches what you copied, that it is prefixed with `Bearer` , and that it is not in the revoked section of the Developer tab.
Tool calls hang for 30 seconds, then time out Almost always the browser tab is closed, backgrounded, or asleep. Board-editing tools run in the live session. Open Protoboard, load the target board, and retry; if the tab is open but frozen, refresh to re-register presence. If your agent reports "no boards found," this is the usual cause.
Agent connects, but no Protoboard tools appear The client opened a session but has not refreshed its tool list. In VS Code extensions, run **Restart MCP servers** from the command palette. In CLI agents, quit and relaunch, or re-run `/mcp`.
Old auth errors persist after rotating a key Some clients cache the handshake. Remove the server and re-add it: for Claude Code, `claude mcp remove protoboard` then re-run the add command (clear `~/.mcp-auth` if it exists); for Codex and Gemini CLI, delete the `protoboard` block, restart, and re-add.
Running your agent from WSL with Protoboard on Windows `localhost:3000` may not resolve across the WSL boundary. Point the config at `http://host.docker.internal:3000/api/mcp` from WSL, or use the Windows host's LAN IP. Remote URLs like `https://alpha.protoboard.xyz/api/mcp` work the same on both sides.
*** ## Related pages * [**Agent Bridge Overview**](/agent-bridge-mcp/overview.md): what the bridge is and when to reach for it * [**ProtoBot Overview**](/protobot/overview.md): the built-in assistant, no setup required * [**Usage and Energy**](/protobot/usage-and-energy.md): how bridge calls count against your energy budget --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.protoboard.xyz/agent-bridge-mcp/setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.