> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an agent to Brimble MCP

> Point Claude Code, Cursor, or other MCP clients at https://mcp.brimble.io with your Brimble API key.

Connect an AI client to **Brimble MCP** so it can call Brimble tools on your account.

## Prerequisites

* A Brimble account on a plan that allows **API keys**.
* An API key from the dashboard. Prefer a **scoped** key (for example read-only or sandbox-only) while you experiment. See [API keys](/security/api-keys).
* Network access to `https://mcp.brimble.io` (public HTTPS).

## 1. Create an API key

1. Open [the dashboard](https://app.brimble.io).
2. Go to **Settings → API keys** (or your profile / team API keys surface).
3. Create a key with the permissions you want the agent to have.
4. Copy the secret once (`br_…`). Store it in a password manager or secret store, not in git.

You can confirm the key belongs to you and review its scopes in a connect UI that calls Core's ownership check before you paste the key into a client.

## 2. Choose a client

### Claude Code (recommended for local agents)

HTTP transport with a Bearer token (the API key):

```bash theme={null}
claude mcp add --transport http brimble https://mcp.brimble.io \
  --header "Authorization: Bearer $BRIMBLE_API_KEY"
```

Or with the Brimble header name:

```bash theme={null}
claude mcp add --transport http brimble https://mcp.brimble.io \
  --header "x-brimble-key: $BRIMBLE_API_KEY"
```

### Cursor / Claude Desktop-style config

Many clients accept a JSON MCP config. Example shape (field names vary slightly by app):

```json theme={null}
{
  "mcpServers": {
    "brimble": {
      "url": "https://mcp.brimble.io",
      "headers": {
        "Authorization": "Bearer br_..."
      }
    }
  }
}
```

Equivalent:

```json theme={null}
{
  "mcpServers": {
    "brimble": {
      "url": "https://mcp.brimble.io",
      "headers": {
        "x-brimble-key": "br_..."
      }
    }
  }
}
```

Use environment variable substitution if your client supports it, so the key never sits in a committed file.

### Anthropic Messages API MCP connector

When attaching a remote MCP server from the API, pass the same key as `authorization_token` (sent as Bearer to the server):

```json theme={null}
{
  "type": "url",
  "url": "https://mcp.brimble.io",
  "name": "brimble",
  "authorization_token": "br_..."
}
```

## 3. Optional team context

If tools should run in a specific team workspace, set:

```http theme={null}
x-brimble-team: <team-id>
```

in the client headers (alongside the API key). Leave it off for personal account context when the key is personal.

## 4. Verify the connection

1. Confirm the service is up:

   ```bash theme={null}
   curl -sS https://mcp.brimble.io/health
   ```

   You should see `"status":"ok"` and `"service":"brimble-mcp"`.

2. In the agent, list tools or ask something only Brimble can answer (for example, list your projects).

3. If the agent gets auth errors, re-check the key, header name, and that the key was not rotated.

## Auth summary

| Header                    | Value                      |
| ------------------------- | -------------------------- |
| `Authorization: Bearer …` | Your API key (`br_…`)      |
| `x-brimble-key: …`        | Same API key (alternative) |
| `x-brimble-team: …`       | Optional team id           |

Brimble MCP maps Bearer or `x-brimble-key` to Core as **`x-brimble-key`**. The agent never needs a dashboard session JWT; that JWT is only for browser ownership checks when pasting a key in the dashboard.

## Troubleshooting

**`401` / invalid API key.**\
Wrong or rotated key, or missing header. Confirm `curl` with the same header against a Core route or re-copy the key from the dashboard.

**Tools missing or permission errors.**\
The key's scopes do not include that action. Create a new key with the required permissions, or use a broader preset only if you accept the risk.

**Browser shows an error on `https://mcp.brimble.io/`.**\
Expected. The root path is the MCP protocol endpoint, not a website. Use `/health` to check liveness.

## Next steps

* [Brimble MCP overview →](/mcp/overview)
* [API keys →](/security/api-keys)