> 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/setup.md). # Setup Create an agent API key and connect Claude Code, Claude Desktop, Cursor, VS Code, Codex or another MCP client to Protoboard over HTTP ## Goal Connect your MCP client to Protoboard in three steps: create a key, add the server to your client, and check the connection. Any plan can create agent keys. | Setting | Value | | ----------- | ---------------------------------------------------- | | Server name | `protoboard` | | URL | `https://alpha.protoboard.ai/api/mcp` | | Transport | Streamable HTTP | | Auth | Header `Authorization: Bearer pb_agent_…` (no OAuth) | ## 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 {% embed url="" %} Create an agent API key {% endembed %} [Animated GIF](https://cdn.protoboard.ai/docs/clips/mcp-key-light.gif) · Steps: 1. Open **Settings** (sidebar, or the avatar menu) and choose **Developer**. 2. Under **Agent API Keys**, name the key after where it lives, for example `Claude Code laptop`. 3. Click **Create**, then **Copy key**. The key is shown only once. 4. Click **Done**. Create one key per agent and machine, so you can revoke one without breaking the others. See [API keys](/agent-bridge/api-keys.md). {% hint style="danger" %} **Treat the key like a password.** Anyone with it can run tools on your open boards. Don't commit keys to version control; use an environment variable or your OS secret store where your client supports it. {% endhint %} ## Step 2: Configure your client Each tab installs Protoboard for your user, so every session of that client can use it. To share a config with a team through version control, use the **Project scope alternative** in each tab, with the key kept out of the file. {% tabs %} {% tab title="Claude Code" %} ```bash claude mcp add-json --scope user protoboard '{"type":"http","url":"https://alpha.protoboard.ai/api/mcp","headers":{"Authorization":"Bearer pb_agent_YOUR_KEY_HERE"}}' ``` Or with flags: ```bash claude mcp add --transport http --scope user protoboard https://alpha.protoboard.ai/api/mcp \ --header "Authorization: Bearer pb_agent_YOUR_KEY_HERE" ``` **Verify:** run `claude mcp list` (protoboard shows as connected), or `/mcp` inside a session.
Project scope alternative Add this to `.mcp.json` at the project root. Claude Code expands `${PB_AGENT_KEY}` from the environment, so the key stays out of the file. Claude Code asks you to approve project servers the first time. ```json { "mcpServers": { "protoboard": { "type": "http", "url": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer ${PB_AGENT_KEY}" } } } } ```
Docs: [Claude Code MCP](https://code.claude.com/docs/en/mcp) {% endtab %} {% tab title="Claude Desktop" %} Claude Desktop connects to Protoboard through [`mcp-remote`](https://github.com/geelen/mcp-remote), a small bridge that runs with `npx` and adds the key header. You need [Node.js](https://nodejs.org) installed. 1. In Claude Desktop, open **Settings > Developer > Edit Config**. This opens `claude_desktop_config.json`: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the server: ```json { "mcpServers": { "protoboard": { "command": "npx", "args": [ "mcp-remote", "https://alpha.protoboard.ai/api/mcp", "--header", "Authorization: Bearer ${PB_KEY}" ], "env": { "PB_KEY": "pb_agent_YOUR_KEY_HERE" } } } } ``` 3. Quit and restart Claude Desktop. **Verify:** open the **+** menu in a chat, then **Connectors**, and check that `protoboard` is listed and on. Logs are in `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs` (Windows). {% hint style="warning" %} **On Windows**, spaces inside `args` can be split incorrectly. Use `"Authorization:${AUTH_HEADER}"` (no space after the colon) as the header argument, and set `"AUTH_HEADER": "Bearer pb_agent_YOUR_KEY_HERE"` in `env`. {% endhint %} The **Add custom connector** option in Claude's settings expects OAuth unless your organization has the request-headers option for connectors. Protoboard uses API keys, so use `mcp-remote` as shown. {% endtab %} {% tab title="Cursor" %} Add the server to `~/.cursor/mcp.json`: ```json { "mcpServers": { "protoboard": { "url": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer ${env:PB_AGENT_KEY}" } } } } ``` Set `PB_AGENT_KEY` in the environment Cursor starts from, or replace `${env:PB_AGENT_KEY}` with the key. **Verify:** check that `protoboard` is enabled in Cursor's MCP settings, and look in the Output panel under **MCP Logs** if it doesn't connect.
Project scope alternative Put the same JSON in `.cursor/mcp.json` at the project root. Keep `${env:PB_AGENT_KEY}` so the key stays out of the file.
Docs: [Cursor MCP](https://cursor.com/docs/context/mcp) {% endtab %} {% tab title="VS Code" %} For GitHub Copilot agent mode. Run **MCP: Open User Configuration** from the Command Palette and add: ```json { "inputs": [ { "type": "promptString", "id": "pb-agent-key", "description": "Protoboard agent API key", "password": true } ], "servers": { "protoboard": { "type": "http", "url": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer ${input:pb-agent-key}" } } } } ``` VS Code asks for the key the first time the server starts and stores it securely. **Verify:** run **MCP: List Servers**, select `protoboard` and choose **Show Output**.
Project scope alternative Put the same JSON in `.vscode/mcp.json` in the workspace. The `inputs` prompt keeps the key out of the file.
Docs: [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) {% endtab %} {% tab title="Codex" %} Add the server to `~/.codex/config.toml`: ```toml [mcp_servers.protoboard] url = "https://alpha.protoboard.ai/api/mcp" bearer_token_env_var = "PB_AGENT_KEY" ``` Then set the variable where you run Codex: ```bash export PB_AGENT_KEY=pb_agent_YOUR_KEY_HERE ``` Or add it from the command line: ```bash codex mcp add protoboard --url https://alpha.protoboard.ai/api/mcp --bearer-token-env-var PB_AGENT_KEY ``` **Verify:** run `codex mcp list`, or `/mcp` in the Codex TUI.
Project scope alternative Put the same TOML block in `.codex/config.toml` at the project root. Codex loads project config only for projects you trust.
Docs: [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) {% endtab %} {% tab title="Other clients" %} Any MCP client that supports Streamable HTTP and custom headers works. Point it at `https://alpha.protoboard.ai/api/mcp` with the header `Authorization: Bearer pb_agent_YOUR_KEY_HERE`. A client that only supports stdio servers can use [`mcp-remote`](https://github.com/geelen/mcp-remote) as shown in the Claude Desktop tab. **Gemini CLI** (`~/.gemini/settings.json`, or `.gemini/settings.json` for project scope). Use `httpUrl`; `url` means the older SSE transport: ```json { "mcpServers": { "protoboard": { "httpUrl": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer pb_agent_YOUR_KEY_HERE" } } } } ``` Verify with `gemini mcp list` or `/mcp`. **Zed** (`settings.json`): ```json { "context_servers": { "protoboard": { "url": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer pb_agent_YOUR_KEY_HERE" } } } } ``` **Windsurf / Devin Desktop** (`mcp_config.json`): ```json { "mcpServers": { "protoboard": { "serverUrl": "https://alpha.protoboard.ai/api/mcp", "headers": { "Authorization": "Bearer ${env:PB_AGENT_KEY}" } } } } ``` {% endtab %} {% endtabs %} ## Step 3: Verify the connection 1. Open a board in Protoboard in a signed-in browser tab. 2. Ask your agent: "What Protoboard boards do I have open?" It should name the board. 3. A green **AGENT** pill appears next to the board name. Click it to open **Agents > External**, which lists each connected key with its call count and a **Disconnect agent from board** button.
The editor header with a green AGENT pill, and the Agents panel External tab listing a connected agent key with its call count

A connected agent.

## Working with boards and keys * **One board open:** the agent connects automatically. **Several open:** it uses `list_boards`, then `connect_board`, and stays on that board until it switches. * **Rename or revoke** keys in **Settings > Developer**. Revoking takes effect on the next call. Update your client config afterwards so it stops retrying with a dead key. ## Common failures See [Agent Bridge troubleshooting](/agent-bridge/troubleshooting.md) for 401 errors, queued calls, missing tools and stale credentials. ## Related pages * [Agent Bridge overview](/agent-bridge/overview.md) * [API keys](/agent-bridge/api-keys.md) * [Tool reference](/agent-bridge/tool-reference.md) * [Connect Claude Code through MCP](/tutorials/connect-claude-code.md)