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 "<your agent name>, <this machine>") 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

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

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.

---

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.

Claude Code

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:

{
  "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.

OpenAI Codex

Add the server to ~/.codex/config.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:

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.

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.

Gemini CLI

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "protoboard": {
      "httpUrl": "https://alpha.protoboard.xyz/api/mcp",
      "headers": {
        "Authorization": "Bearer pb_agent_YOUR_KEY_HERE"
      }
    }
  }
}

Or from the command line:

gemini mcp add protoboard \
  --httpUrl https://alpha.protoboard.xyz/api/mcp \
  --header "Authorization: Bearer pb_agent_YOUR_KEY_HERE"

Verify with /mcp list.

Use protoboard as the server name. Gemini CLI namespaces tools as mcp_<server>_<tool>, so avoid underscores in the name itself.

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.

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.

---

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

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

---

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: what the bridge is and when to reach for it

• ProtoBot Overview: the built-in assistant, no setup required

• Usage and Energy: how bridge calls count against your energy budget