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

# Connect a client

> Configuring Claude, Cursor and other MCP clients against your Peeve endpoint.

Your endpoint is an HTTP JSON-RPC MCP server. Any client that speaks MCP over
HTTP can connect.

Before you start, check the two preconditions from
[the overview](/mcp/overview): your plan is Growth or above, and the agent
channel is enabled with the kill switch off. Confirm with a `GET`:

```bash theme={null}
curl https://api.peeve.ai/api/mcp/{workspace} \
  -H "Authorization: Bearer pv_ut_xxx"
```

A discovery card with a `tools` count means you are ready. An
`{"error": "not_available"}` means one of the preconditions is unmet.

## Claude

Add the server in Claude's connector settings, pointing at your endpoint URL:

```
https://api.peeve.ai/api/mcp/{workspace}
```

or the friendly form:

```
https://mcp.peeve.ai/{workspace}
```

For a [per-user grant](/mcp/per-user-grants), use the `/u/{contact}` URL and
supply the `pv_grant_…` token as a bearer credential.

## Cursor

In `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):

```json theme={null}
{
  "mcpServers": {
    "example-corp": {
      "url": "https://api.peeve.ai/api/mcp/00000000-0000-4000-8000-000000000000"
    }
  }
}
```

With a per-user grant:

```json theme={null}
{
  "mcpServers": {
    "example-corp": {
      "url": "https://api.peeve.ai/api/mcp/00000000-0000-4000-8000-000000000000/u/11111111-1111-4111-8111-111111111111",
      "headers": {
        "Authorization": "Bearer pv_grant_xxx"
      }
    }
  }
}
```

<Warning>
  A grant token in a config file is a credential in a file. Do not commit
  `.cursor/mcp.json` with a real token in it.
</Warning>

## Any MCP client

If your client needs the details spelled out:

|                  |                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------- |
| Transport        | HTTP, JSON-RPC 2.0                                                                    |
| Protocol version | `2024-11-05`                                                                          |
| Method           | `POST` for RPC; `GET` returns a discovery card                                        |
| Content type     | `application/json`                                                                    |
| Auth             | `Authorization: Bearer pv_ut_…` (workspace) or `pv_grant_…` / `pv_ut_…` (per-contact) |
| Allowed headers  | `Content-Type`, `Authorization`, `Mcp-Session-Id`                                     |
| Batching         | Supported — send an array                                                             |
| `listChanged`    | `false` — re-list rather than waiting for a push                                      |

## Verifying by hand

```bash theme={null}
WS=00000000-0000-4000-8000-000000000000

# Handshake
curl -sX POST https://api.peeve.ai/api/mcp/$WS \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# What tools exist
curl -sX POST https://api.peeve.ai/api/mcp/$WS \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call one
curl -sX POST https://api.peeve.ai/api/mcp/$WS \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"invite_teammate","arguments":{}}}'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="tools/list returns an empty array">
    The endpoint is working, but nothing is projected. Every tool must come from
    a capability that is in the current production map, verified, marked
    agent-accessible, and not disabled. Check those four in the dashboard.

    A workspace with no production map version at all projects nothing — run the
    baseline capture first.
  </Accordion>

  <Accordion title="&#x22;Agent channel not available for this workspace.&#x22;">
    One of: the workspace id is wrong; the plan is below Growth; the agent
    channel is switched off; the kill switch is on. The message is deliberately
    the same for all of them, so work through them in that order.
  </Accordion>

  <Accordion title="&#x22;Invalid or revoked grant token.&#x22;">
    Per-user endpoint only. The token is missing, malformed, revoked, expired,
    or bound to a different contact or workspace than the URL. Check the
    `Authorization: Bearer` header is actually being sent — some clients drop
    custom headers silently.
  </Accordion>

  <Accordion title="429 Rate limited">
    You are above your plan's ceiling. Honour the `retry-after` header. If a
    client is polling `tools/list`, stop — the list does not push changes, and
    re-listing on a timer is what usually causes this.
  </Accordion>

  <Accordion title="The assistant says it completed an action">
    It did not. `tools/call` returns guidance only. If an assistant reports
    having performed a write through this server, that is the assistant
    over-claiming — nothing on the Peeve side executed. See
    [the overview](/mcp/overview).
  </Accordion>
</AccordionGroup>