Peeve
Peeve เป็นเอเจนต์ AI สำหรับฝ่ายสนับสนุนลูกค้าของ SaaS MCP server ที่โฮสต์ไว้จะมอบความสามารถที่ผ่านการตรวจสอบแล้วของผลิตภัณฑ์คุณให้แก่เอเจนต์ของผู้ใช้ (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 | |
|---|---|---|
| Direction | Assistants, to Peeve | Peeve, to your server |
| Peeve's role | Server | Client |
| Who connects | Claude, ChatGPT, Cursor | Peeve, to a server you run |
| Executes? | Some tools do. See what a tool call does | Yes, 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}/meOne 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 same401as 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/v1API 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 call | What 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 endpoint | Opens a hand-off, so a person answers rather than the customer getting a refusal. |
| Any other capability tool | Returns 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.
| Tool | What it does | Role it needs |
|---|---|---|
peeve_reply_handoff | Replies 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_status | Changes a lead's status on the Leads board. | grant (owner, admin) |
Before either one runs, four things are checked in order:
- Scope. A customer connection is refused: these change the workspace's data, and no customer's assistant reaches a teammate's authority.
- Role, with the same check
/v1uses. A role that cannot reply in the dashboard cannot reply here. - The switches. The kill switch outranks everything, then the workspace's own agent-writes switch (Settings → Guardrails).
- 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_actionsgates thepeeve_*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:
| Setting | Effect |
|---|---|
| Customer access: immediate (default) | A customer's own API token for your product opens their endpoint. Nobody has to issue anything. |
| Customer access: approval | Only 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: off | No customer endpoint opens at all, issued grants included. |
| Where customers sign in | The 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.
| Method | Behaviour |
|---|---|
initialize | Returns 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. |
ping | Returns {}. |
tools/list | Lists the projected capability tools, then any peeve_* tools the credential actually holds. |
tools/call | One 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.