Workspace endpoint

GET  https://mcp.peeve.ai/{workspace}
POST https://mcp.peeve.ai/{workspace}

mcp.peeve.ai is the address to hand to an assistant — it is what the dashboard shows and what GET /v1/contacts returns as mcp_url. It rewrites to the app’s own /api/mcp/{workspace} route, which also works if you need the origin directly. workspaceId is your workspace UUID, from Settings → Workspace. Anything that is not a well-formed UUID returns 404.

This endpoint requires an API token. Send a teammate’s pv_ut_… token as Authorization: Bearer. It previously took no credential; it does now.The token’s workspace must match the id in the URL. A token for another workspace gets the same 404 as a workspace that does not exist — the endpoint deliberately cannot be walked as an oracle for which workspace ids are real, which is also why a mismatch is not a 403.Any role satisfies it (read) — the same gate the dashboard applies to viewing the console. Which tools are reachable is governed by that role; see Roles.

GET — discovery card

A small card for humans and directories.

curl https://mcp.peeve.ai/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer pv_ut_xxx"

{
  "name": "Example Corp · Peeve MCP",
  "protocol": "mcp",
  "protocolVersion": "2024-11-05",
  "transport": "http-jsonrpc",
  "endpoint": "/api/mcp/00000000-0000-4000-8000-000000000000",
  "tools": 12,
  "hint": "POST JSON-RPC here: initialize, tools/list, tools/call."
}

The endpoint field is the app’s own path, not the friendly host — that is what the server returns. Keep using mcp.peeve.ai when handing the address to a client.

Not cached (Cache-Control: private, no-store) — it is behind a credential, and a shared cache in front of an authenticated endpoint is how one tenant ends up served another’s response.

POST — JSON-RPC

`initialize`

curl -X POST https://mcp.peeve.ai/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer pv_ut_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "Example Corp · Peeve", "version": "1.0.0" },
    "instructions": "Verified capabilities for Example Corp. Each tool returns a grounded guide — where the capability lives and how to complete it. Writes are completed by the user in-product, never executed by this server."
  }
}

Note listChanged: false — the tool list does not push updates. Clients should re-list rather than wait for a notification.

The instructions string is what the server sends today, and it describes today’s behaviour rather than a permanent guarantee. Writes through MCP happen in the other direction, via the Custom MCP connector.

`tools/list`

curl -X POST https://mcp.peeve.ai/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer pv_ut_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "invite_teammate",
        "description": "Invite a teammate to the workspace",
        "inputSchema": {
          "type": "object",
          "properties": { "email": { "type": "string" } },
          "required": ["email"]
        },
        "annotations": {
          "title": "invite_teammate",
          "destructiveHint": false,
          "confirmationRequired": true,
          "readOnlyHint": false
        }
      }
    ]
  }
}

The annotations tell a client how to treat each tool:

Annotation	Meaning
`readOnlyHint`	The capability only reads or navigates. Safe to act on directly.
`confirmationRequired`	The user must confirm before it is completed. True for any write and anything destructive.
`destructiveHint`	The capability destroys or irreversibly changes something.

These annotations describe the capability, not this endpoint. No tool call here executes anything, whatever its annotations say — they exist so a client can present the guidance with the right weight.

`tools/call`

curl -X POST https://mcp.peeve.ai/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer pv_ut_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": { "name": "invite_teammate", "arguments": { "email": "sam@example.com" } }
  }'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invite a teammate to the workspace\n\nWhere in Example Corp: /settings/team\nPermission: write — needs the user's confirmation\n\nThis changes data. Guide the user to complete it themselves in the product — do not assume it was executed here."
      }
    ],
    "isError": false
  }
}

No invite was sent. The response is guidance for the assistant to relay, and the arguments are not acted on. See the overview for why.

An unknown tool name returns -32602 Unknown tool: {name}; a missing name returns -32602 Invalid params: missing tool name.

Batching

[
  { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} },
  { "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
]

Returns an array of responses, with notifications omitted. If a batch contains only notifications, the response is 202 with no body.

Errors

MCP clients expect protocol errors as 200 responses with a JSON-RPC error member, and that is what Peeve returns — with two exceptions noted below.

Condition	HTTP	JSON-RPC code	Message
Unparseable body	200	`-32700`	Parse error
Missing `method`	200	`-32600`	Invalid request: missing method
Unknown method	200	`-32601`	Method not found: …
Bad or missing tool name	200	`-32602`	Unknown tool: …
Missing token, or not a live API token	401	—	Unauthenticated
Token for a different workspace, or no such workspace	404	—	Identical refusal for both, deliberately
Role cannot use MCP	403	—	Insufficient role
Not entitled, disabled or killed	200	`-32001`	Agent channel not available for this workspace.
Rate limited	429	`-32002`	Rate limited — slow down.
Platform unavailable	503	`-32001`	Agent channel not available for this workspace.

Rate limiting is a real 429 with a retry-after header on purpose, so a client backs off properly instead of retrying into the wall.

A -32001 does not distinguish “no such workspace” from “not entitled” — both look the same from outside. If you are debugging, check in order: the workspace id is a valid UUID; the plan is Growth or above; the agent channel is enabled; the kill switch is off.

Rate limits

Bucketed per workspace and per credential, with ceilings that follow your plan; see Rate limits. The limiter runs before the capability projection, so a shed request costs nothing. Like every limiter in Peeve it fails open: if the limiter itself is unavailable, requests are allowed rather than blocked.

A friendly hostname

The endpoint is advertised as mcp.peeve.ai/{workspace}, which rewrites to this route. Both work; use whichever you prefer when handing the URL to someone.

Get started

Authentication

Widget

MCP

Webhooks

Reference

Workspace endpoint

GET — discovery card

POST — JSON-RPC

`initialize`

`tools/list`

`tools/call`

Batching

Errors

Rate limits

A friendly hostname

​GET — discovery card

​POST — JSON-RPC

​initialize

​tools/list

​tools/call

​Batching

​Errors

​Rate limits

​A friendly hostname

GET — discovery card

POST — JSON-RPC

`initialize`

`tools/list`

`tools/call`

Batching

Errors

Rate limits

A friendly hostname