Peeve

Peeve — ИИ-агент поддержки клиентов для SaaS. Его размещённый MCP-сервер предоставляет агентам ваших пользователей (Claude, ChatGPT, Cursor) проверенные возможности вашего продукта в виде типизированных инструментов с указанными эффектами и отзывными разрешениями для каждого пользователя. Вызов инструмента возвращает основанное на фактах руководство; изменения выполняются в продукте.

Размещённый MCP-сервер

npx add-mcp 'https://docs.peeve.ai/mcp'

Устанавливается в Claude Code, Codex, Cursor и другие

Документация

MCP server

Connect an assistant to your product over Model Context Protocol: the three endpoints, the credential each one takes, and what a tool call actually does.

Peeve speaks Model Context Protocol in both directions, and they behave very differently. Know which one you mean.

Peeve's MCP server (this page)Custom MCP connector
DirectionAssistants, to PeevePeeve, to your server
Peeve's roleServerClient
Who connectsClaude, ChatGPT, CursorPeeve, to a server you run
Executes?Some tools do. See what a tool call doesYes, behind a confirmation gate

[!NOTE]

If you are asking "can MCP write?", the answer is yes in both directions, but not for everything. On this page a peeve_* tool executes and a capability tool returns a guide; on the connector, Peeve calls your tools behind a confirmation.

The three endpoints

Which one you want depends on who is connecting: a teammate, or one of your customers.

[card] Workspace

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

A teammate's API token (pv_ut_…), acting for the workspace. Any role can read; writing needs the role that would allow it in the dashboard.

[card] Signed-in customer

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

One address for every customer. The person signs in through your app and Peeve mints their token: OAuth, so Claude and ChatGPT can connect it themselves.

[card] One named customer

https://mcp.peeve.ai/{workspace}/u/{contact}

Bound to one contact. Takes that person's own API token for your product, or a pv_grant_… you issue them.

[!WARNING]

A teammate's token opens the workspace endpoint only. On the two customer addresses a pv_ut_… is refused outright, with the same 401 as no credential at all.

That is deliberate: a teammate reading one customer's data is not that customer conversing, and Peeve will not meter it as though it were. Teammates use the workspace endpoint; customers use theirs.

[!WARNING]

Treat an MCP token as full account reach, not "an MCP key".

The pv_ut_… you point an assistant at MCP with is the same credential that reaches the whole /v1 API at that person's live role, including, for an owner or admin, writing guardrails, re-statusing leads and operating the kill switch.

So scope by who you issue it to, not by what you intend to use it for. There is no MCP-only token. Hand one to a teammate whose role is as narrow as the job allows, and revoke it in Settings → API keys when the integration ends.

What a tool call actually does

There are four outcomes, and which one you get depends on the tool and the endpoint. Nothing here is ambiguous at call time: a tool that did not run says so in words an assistant cannot read as success.

You callWhat happens
peeve_reply_handoff, peeve_set_lead_status (workspace endpoint)Executes. The same writers the dashboard and /v1 use, behind the same role, the same workspace switches and the same plan gate. Audited.
peeve_ask, peeve_talk_to_human (a customer's endpoint)Runs a real conversation turn. It is transcribed, it can open a hand-off, and it costs a credit like any other channel.
A human-only capability on a customer's endpointOpens a hand-off, so a person answers rather than the customer getting a refusal.
Any other capability toolReturns a grounded guide: where the capability lives in your product, and how to complete it.

[!NOTE]

Why a capability tool will never execute. A capability is performed by moving a real cursor inside the visitor's own authenticated browser session. An MCP client has no browser on your site, no page and no session, so there is nothing for it to click. That is a category difference rather than a gap waiting to be filled.

What can run server-side is Peeve's own data (replying to a hand-off, moving a lead), and those are exactly the tools named peeve_*.

The write tools

Advertised on the workspace endpoint only, and filtered by role before they are named, so an assistant is never offered a tool its token cannot run.

ToolWhat it doesRole it needs
peeve_reply_handoffReplies to a hand-off on the channel the conversation started on, optionally resolving it. Attributed to the teammate whose token is in use.reply (owner, admin, responder)
peeve_set_lead_statusChanges a lead's status on the Leads board.grant (owner, admin)

Before either one runs, four things are checked in order:

  1. Scope. A customer connection is refused: these change the workspace's data, and no customer's assistant reaches a teammate's authority.
  2. Role, with the same check /v1 uses. A role that cannot reply in the dashboard cannot reply here.
  3. The switches. The kill switch outranks everything, then the workspace's own agent-writes switch (Settings → Guardrails).
  4. The plan. Executing actions over MCP needs Growth or above (agent_actions).

A refusal comes back as a tool result with isError: true and the sentence "It was NOT performed." The kill switch is not operable from here, on purpose: turning Peeve off is a dashboard action, and an emergency stop is the one control a misread instruction should never reach.

Conversation turns

On a customer's endpoint, the connection is a channel, not a data feed. peeve_ask runs the same grounded answerer that email, WhatsApp, Messenger, Instagram and POST /v1/answer run. peeve_talk_to_human opens the ordinary hand-off, with the same PV-#### reference a widget chat produces.

Each turn lands in Sessions and, where it escalates, in Hand-offs. A teammate answers it exactly as they answer a widget chat; there is no separate inbox to learn. The customer's message is written to the thread before the answerer runs, so a failure leaves the question for a person rather than losing it.

[!NOTE]

A conversation turn uses a credit, on the same terms as every other channel: one per conversation per rolling 24 hours. Capability guides and the peeve_* write tools are not conversation turns and are not metered.

When the workspace is out of credits, both tools refuse and say nothing was sent.

What it exposes

Capability tools are projected from your workspace's verified capabilities, the ones Peeve has confirmed exist in your product by mapping it. A capability appears as a tool only when all of the following hold:

  • it belongs to the current production version of your product map;
  • its status is verified, not draft, stale or broken;
  • its agent access is set to allowed, or to human-only (which a teammate's connection sees, labelled as a person's to finish);
  • it has not been disabled by a builder.

Everything else is invisible to an assistant. Nothing is hand-written; the projection is generated from the same graph that grounds the in-product agent, so the two can never disagree about what your product does.

Plans and limits

[!WARNING]

Reaching the channel is on every plan, Starter and trial included (agent_channel). What Growth buys is the assistant acting: agent_actions gates the peeve_* write tools, not the connection.

Three things can still close the channel on any plan: the agent channel must be enabled for the workspace, the kill switch must be off, and the subscription must be live. Any of those answers "agent channel not available for this workspace".

Customer connections have two further controls, both in Agents → Policy:

SettingEffect
Customer access: immediate (default)A customer's own API token for your product opens their endpoint. Nobody has to issue anything.
Customer access: approvalOnly a pv_grant_… an owner or admin issued opens it. A token the customer minted by signing in stops working on the next request.
Customer access: offNo customer endpoint opens at all, issued grants included.
Where customers sign inThe URL in your app that the OAuth flow sends them to. Required for /me.

Grants are also capped per person by plan: 5 on Starter, 20 on Growth, unlimited on Scale. A trial gets the Starter cap, and revoking one frees a slot.

Protocol

JSON-RPC 2.0 over HTTP. Protocol version 2024-11-05, negotiated in the initialize handshake.

MethodBehaviour
initializeReturns the protocol version, server info and instructions. The instructions name the two kinds of tool, and say outright that a tool reporting "NOT performed" did nothing.
pingReturns {}.
tools/listLists the projected capability tools, then any peeve_* tools the credential actually holds.
tools/callOne of the four outcomes above.

Anything else returns -32601 Method not found.

Notifications, meaning a message with no id or any method in the notifications/* namespace, get no reply. A batch consisting only of notifications is answered 202 with no body.

Batches are supported: send an array, get an array back.

[!NOTE]

There is no version segment in the URL, on purpose. MCP negotiates its protocol version in the handshake and tool changes are additive, so the URL you paste into an assistant stays valid indefinitely.

A guide, in full

{
  "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
  }
}

The guide names the capability's purpose, where it lives (a deep link, or the route path), and its permission class. For anything that changes data it says so explicitly. For a read or navigation capability it says the assistant is safe to walk the user there directly.

The permission line is one of five values, quoted here exactly as the server writes them:

read
write
write — needs the user's confirmation
destructive — needs the user's confirmation
a person's to complete

Auditing

Every tools/call and every initialize lands in your activity log, written after the response so it never slows a call.

Each line carries the credential that made the call, its owner and the role the resolver decided on for that request, plus the tool name, the method and the scope. A peeve_* tool adds its own line with the outcome in words. What never appears is the arguments, which can carry a customer's own message text.

On a customer's endpoint the line is attributed to that contact, so you can see whose assistant did what rather than "someone with the URL".

Next

[card] Workspace endpoint

Full request and response shapes, and the write tools.

[card] Customer endpoints

Sign-in, grants, and the conversation tools.

[card] Connect a client

Claude, ChatGPT, Cursor, Claude Code and generic MCP clients.

[card] Custom MCP connector

The other direction: Peeve calling your MCP server.

This documentation is built and hosted on Mintlify, a developer documentation platform.