> 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/tutorials/connect-claude-code.md).

# Connect Claude Code through MCP

Create an agent API key, add the Protoboard MCP server to Claude Code and let it work on a board you have open

## Goal

Connect Claude Code to Protoboard so it can read and edit the Line-Following Robot board you have open, using the same tools ProtoBot uses. Other clients (Claude Desktop, Cursor, VS Code, Codex) are covered in [Agent Bridge setup](https://docs.protoboard.xyz/agent-bridge/setup.md).

{% hint style="info" %}
**Time:** 5 minutes. **You need:** [Claude Code](https://code.claude.com/docs/en/overview) installed, and a Protoboard account on any plan. MCP calls don't use ProtoBot Energy.
{% endhint %}

## Steps

{% stepper %}
{% step %}

### Create an agent API key

{% embed url="<https://cdn.protoboard.ai/docs/clip/mcp-key?title=Create+an+agent+API+key>" %}
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**, type a name that says where the key lives, for example `Claude Code laptop`.
3. Click **Create**.
4. Click **Copy key**. The key starts with `pb_agent_` and is shown only once.
5. Click **Done**.

{% hint style="danger" %}
Treat the key like a password. Anyone with it can run tools on your open boards. Don't commit it to a repository.
{% endhint %}
{% endstep %}

{% step %}

### Add the server to Claude Code

In a terminal, run this with your key in place of `pb_agent_YOUR_KEY_HERE`:

```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"}}'
```

`--scope user` makes Protoboard available in every Claude Code session on this machine.
{% endstep %}

{% step %}

### Check the connection

1. Run `claude mcp list`. `protoboard` should show as connected.
2. Start Claude Code and run `/mcp` to see the Protoboard tools.
   {% endstep %}

{% step %}

### Open a board and try it

1. In the browser, open the **Main controller** board.
2. Ask Claude Code: `What Protoboard boards do I have open?` It calls `list_boards` and connects to the board.
3. Ask: `Run DRC on the board and summarize any issues.`

A green **AGENT** pill appears next to the board name. Click it to open **Agents > External**, which lists the connected key and its call count.

<figure><picture><source srcset="https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-8ff1cb11bbc0ee985ab7ae3ba0b8a4d474b24224%2Fmcp-agent-pill-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-9fb6438d4c8a39b05e229af51e649050f520deb0%2Fmcp-agent-pill-light.png?alt=media" alt="The editor header with a green AGENT pill next to the board name, and the Agents panel on the External tab listing the connected key Claude Code laptop with its call count"></picture><figcaption><p>The AGENT pill and the External tab.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Result

Claude Code can now search the library, place and wire parts, run DRC and manage the BOM on any board you open. The connection sticks to one board until you ask it to switch with `connect_board`. The full list is in the [Tool reference](https://docs.protoboard.xyz/agent-bridge/tool-reference.md).

## Common failures

<details>

<summary>401 or "Unauthorized"</summary>

The key is wrong, revoked, or missing the `Bearer` prefix. Copy the key again (create a new one if you lost it) and re-run the add command after `claude mcp remove protoboard`.

</details>

<details>

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

No board is open in a signed-in browser tab. Open the board, then ask again. If several boards are open, ask Claude Code to use `connect_board` with the one you want.

</details>

<details>

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

The board's tab is asleep in the background. Click the tab to wake it; queued calls run then. See [Agent Bridge troubleshooting](https://docs.protoboard.xyz/agent-bridge/troubleshooting.md).

</details>

## Related pages

* [Agent Bridge overview](https://docs.protoboard.xyz/agent-bridge/overview.md): what the bridge can and can't do
* [Agent Bridge setup](https://docs.protoboard.xyz/agent-bridge/setup.md): every client, user and project scope
* [API keys](https://docs.protoboard.xyz/agent-bridge/api-keys.md): rename, revoke and rotate keys
* [Tool reference](https://docs.protoboard.xyz/agent-bridge/tool-reference.md): every tool your agent can call
