> ## 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.

# Custom MCP connector

> Connect your own MCP server so the agent can call your tools — including writes.

Peeve can act as an **MCP client** against a server you run. Connect it, and the
agent gains your tools on top of what it can already do on the page.

<Warning>
  **This is the direction where writes happen.** It is the opposite of
  [Peeve's own MCP server](/mcp/overview), where Peeve is the *server* and
  `tools/call` returns guidance. Here Peeve is the *client*, and a tool call
  really runs against your system.

  |              | Peeve's MCP server | This connector          |
  | ------------ | ------------------ | ----------------------- |
  | Direction    | Assistants → Peeve | Peeve → **your** server |
  | Peeve's role | Server             | Client                  |
  | Executes?    | No                 | **Yes**                 |
</Warning>

**Requires Growth or above** (`custom_mcp`).

## Connecting

**Connectors → Custom MCP.** Give it your server's URL and a token; Peeve seals
the token and starts an async build.

The build runs a real MCP handshake — `initialize`, then a paginated
`tools/list` — off the response path. On success the discovered tools are stored,
the connector flips to `ready`, and the workspace is emailed. On failure it flips
to `failed` with the error, and the owner and admins are emailed.

So the connector has three states: `building`, `ready`, `failed`. A rebuild
re-runs discovery against the stored URL.

<Note>
  Your URL is SSRF-guarded on every connection, the handshake is timed out, and
  the response body is size-capped. Private, loopback and link-local addresses
  are refused, the same as [webhook destinations](/webhooks/outbound).
</Note>

## Tools are classified read or write

At build time each discovered tool is classified from its name, description and
input schema.

| Class          | Meaning                             |
| -------------- | ----------------------------------- |
| `read`         | A pure lookup with no side effects. |
| `write`        | Anything that changes something.    |
| *unclassified* | Classification could not run.       |

<Warning>
  **Only an explicit `read` is treated as safe. Unclassified counts as a write**,
  and so does any tool the classifier omitted. The gate fails closed, so a tool
  Peeve is unsure about gets the strict path, never the permissive one.
</Warning>

## The write gate

Every call runs through the gate **before** it reaches your server — a blocked
write never leaves Peeve. Reads pass straight through. A write must clear all of
this:

<Steps>
  <Step title="The kill switch is off">
    On, and nothing runs — reads included.
  </Step>

  <Step title="Agent writes are enabled for the workspace">
    Otherwise: *"agent writes are turned off for this workspace"*.
  </Step>

  <Step title="The workspace is not in answer-and-show-only mode">
    In `answer_show`, the agent explains and demonstrates but never commits.
  </Step>

  <Step title="The tool is on the write allow-list">
    Listed as `custom_mcp.<toolName>`. Anything not on it is refused by name.
  </Step>

  <Step title="A human has confirmed it">
    **Writes always require an explicit confirmation — even in `auto` mode.**
    There is no configuration that lets a write run unconfirmed.
  </Step>
</Steps>

The tool must also still be enabled; a disabled tool is refused whatever its
class, and enablement is re-checked at call time as well as at the gate.

<Note>
  A refused write returns `requiresConfirmation` when confirmation is the only
  thing missing, so the agent can ask rather than fail. Every other refusal comes
  back with a reason naming the specific gate.
</Note>

## Cost

Each executed tool call **meters one credit**. Reads and writes cost the same.
See [Plans and gating](/reference/plans) for how credits behave when the pool
runs out.

## What the agent sees

Connected tools are offered to the agent as reference — names and descriptions —
so it can use them for requests the page alone cannot satisfy.

<Warning>
  **Tool names and descriptions are untrusted text.** The agent treats them as
  data describing what is available, never as instructions. No text in a tool
  name, description or result can direct the agent's behaviour, and none of it
  can waive the confirmation requirement above.
</Warning>

Peeve still prefers to guide on the page where it can; a connector tool is
reached when the page cannot answer the request.