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

# Connecting an MCP Client

> Wire Claude Code or any MCP client to the Sapot MCP server with a scoped agent key and account header.

Point a coding agent at your account by registering the Sapot Chat MCP server. This page covers the connection contract, the `claude mcp add` command, the `.mcp.json` shape, how to verify, and how to remove or rotate a key.

## The connection contract

The MCP server is a **stateless Streamable-HTTP proxy** (built on FastMCP) that lives at `<mcp-url>/mcp`. It runs no inference and holds no credentials — on every request it simply relays your scoped agent key to the Sapot Chat REST API, which authenticates and authorizes the call.

Every request must carry **two headers**:

| Header               | Value                | Notes                                                           |
| -------------------- | -------------------- | --------------------------------------------------------------- |
| `Authorization`      | `Bearer <agent key>` | The scoped agent key you minted in the dashboard.               |
| `X-Sapot-Account-Id` | `<account id>`       | Your numeric account id (the number in `/app/accounts/<id>/…`). |

<Warning>
  The account id is **fixed by the connection** — it is pinned on the header, never passed as a tool argument. The API independently rejects any request whose account id does not match the key's account, so a key can only ever touch the one account it was minted for.
</Warning>

<Info>
  `Authorization: Bearer …` is preferred. A few MCP clients treat the `Authorization` header specially — those may instead send the key as `X-Api-Access-Token: <agent key>`, which the server accepts as a fallback.
</Info>

## Connect with Claude Code

Register the server in one command:

```bash theme={null}
claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"
```

Replace `https://mcp.sapot.ai/mcp` with your environment's MCP URL, `YOUR_AGENT_KEY` with the key from **Settings → API & Agents**, and `YOUR_ACCOUNT_ID` with your numeric account id.

## Configure via `.mcp.json`

Instead of the CLI, you can declare the server in config. The shape is identical everywhere; only the file location and who it applies to differ.

<Tabs>
  <Tab title="Project level">
    Add a `.mcp.json` at your repo root. This is shared with everyone who works in the project.

    ```json theme={null}
    {
      "mcpServers": {
        "sapot": {
          "type": "http",
          "url": "https://mcp.sapot.ai/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_AGENT_KEY",
            "X-Sapot-Account-Id": "YOUR_ACCOUNT_ID"
          }
        }
      }
    }
    ```

    <Warning>
      A project `.mcp.json` is often committed to source control. Do not check a live agent key into a shared repo — use a per-developer key, an environment variable, or the user-level config below.
    </Warning>
  </Tab>

  <Tab title="User level">
    Register the server once for **all** your projects with the user scope:

    ```bash theme={null}
    claude mcp add --scope user --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"
    ```

    The entry uses the same `mcpServers` shape, stored in your personal Claude Code config rather than in the repo — so your key stays out of shared files.
  </Tab>
</Tabs>

## Verify the connection

<Steps>
  <Step title="Check the server is registered">
    ```bash theme={null}
    claude mcp list
    ```

    The `sapot` server should appear as connected.
  </Step>

  <Step title="List the tools">
    Ask your agent to list its available tools. You will only see the tools your key's scopes unlock — a key with just `conversations:read`, for example, exposes the six conversation read tools. If a whole domain is missing, that scope was not granted. See the scope model in [Authentication & Scopes](/ai-agents/authentication).
  </Step>

  <Step title="Run a read">
    > "List my open conversations."

    A result confirms the key, headers, and account binding all line up.
  </Step>
</Steps>

## Other MCP clients

Any MCP-compatible client connects the same way: **HTTP transport** to `<mcp-url>/mcp`, with the **two headers** on every request (`Authorization: Bearer <agent key>` and `X-Sapot-Account-Id: <account id>`). There is nothing Claude-Code-specific about the server — use your client's own HTTP-server configuration with those values.

## Remove or rotate a key

<Note>
  There is no in-place rotation. To rotate, revoke the old key and mint a new one, then re-point the connection.
</Note>

* **Remove the connection:** `claude mcp remove sapot` (or delete the entry from `.mcp.json` / user config).
* **Rotate the key:** in the dashboard, go to **Settings → API & Agents**, revoke the current key, and create a fresh one. Then re-run `claude mcp add …` (or update `.mcp.json`) with the new key. Revoking a key immediately stops every connection using it.

## When something fails

A denied tool, a `missing the required scope` message, or a `429` quota response are expected, enforced behaviors — not connection bugs. Connection-time and per-call errors are catalogued in [Errors & Quotas](/ai-agents/errors-and-quotas).