# MCP Server

> Reply.io's full sales platform as MCP tools — sequences, contacts, inbox, tasks, and the Jason AI SDR autopilot. Live at mcp.reply.io. High-level reference here — capabilities by domain, contract essentials, connect snippet; full per-argument details at docs.reply.io.

## Status — available today

Reply MCP is an official, live, remote **Streamable HTTP** MCP server exposing Reply.io's
sales-engagement, inbox, AI SDR (Jason), task, account, and help workflows as **MCP tools** for any
MCP-compatible client — Claude, Cursor, Make, n8n, and custom agents.

| | |
|---|---|
| Endpoint | `https://mcp.reply.io/` |
| Transport | Streamable HTTP (JSON-RPC 2.0, MCP protocol `2025-06-18`) |
| Auth | `Authorization: Bearer <key>` |
| Rate limit | Hourly window, ~3000/hour (`X-Rate-Limit-*` headers on every response) |
| Sessions | None required — `initialize` and `tools/list` work without `Mcp-Session-Id` |
| Annotations | Every tool is annotated `readOnlyHint` or `destructiveHint` — gate on them |

## Connect

```bash
claude mcp add --transport http reply https://mcp.reply.io/ \
  --header "Authorization: Bearer YOUR_REPLY_API_KEY"
```

Or in any MCP client config:

```json
{
  "mcpServers": {
    "reply": {
      "type": "http",
      "url": "https://mcp.reply.io/",
      "headers": { "Authorization": "Bearer YOUR_REPLY_API_KEY" }
    }
  }
}
```

Passing credentials in the URL (`?api_key=...`) is not supported — always use the `Authorization`
bearer header. Some clients don't let you set headers at all — typically the **UI/desktop apps** of
Claude, ChatGPT, and Codex, where you add a connector by URL only. Those use OAuth: add
`https://mcp.reply.io/` as a remote connector and authorize when prompted. Note that OAuth is
equivalent to a key with **all scopes** and offers no per-scope control, so prefer a scoped API key
wherever header auth is available. Client-by-client instructions, the `mcp-remote` fallback for
stdio-only clients, and the full OAuth discovery flow:
[docs.reply.io/mcp/connect](https://docs.reply.io/mcp/connect).

## Contract essentials

What an agent needs to know before calling — full rules and the safe-retry matrix at
[docs.reply.io/mcp/tool-contract](https://docs.reply.io/mcp/tool-contract):

- **Responses are SSE frames**; the payload is a JSON string in `result.content[0].text` —
  `{"Success":true,"Data":{...}}` or `{"Success":false,"ErrorCode":"...","ErrorMessage":"..."}`
  (tool errors arrive as HTTP 200 with `isError: true`; branch on `ErrorCode`).
- **Schemas are strict** — `additionalProperties: false`; required fields reject `null`, `""`, `[]`.
- **Pagination is uniform** — `top` (default 20, max 100) + `skip`; iterate until `HasMore` is false.
- **Updates are patches** — omitted fields keep their value; a passed list replaces the whole list.
- **IDs come from resolvers** — resolve exact numeric IDs with `search_*`/`list_*`/`filter_*` tools
  first; never invent one, never ask the user for one.
- **Approvals are addressed by pair** — a Jason draft is identified by `sequenceId` + `contactId`.
  There is no separate draft or message ID.
- **Batches cap at 100, but not all behave alike** — contact batches return per-item results
  (`Affected`, `AffectedContactIds`, `NotProcessed`) and the call as a whole still succeeds, so read
  them and report exact counts ("reassigned 48 of 50"). Bulk approval is **atomic** instead: one
  stale reference rejects the whole batch and nothing is sent.
- **Gate high-stakes tools** — anything that sends, starts outreach, enrolls, blacklists, changes
  ownership, rejects a draft, or switches Jason to Autonomous executes immediately with no undo.
  Confirm with the user first. Note that rejecting a draft is *not* "discard draft": it also removes
  the contact from the sequence. Use regenerate if the user merely dislikes the wording.

## What you can do

Grouped by domain — full signatures, arguments, enums, and failure modes live at
[docs.reply.io/mcp/tools](https://docs.reply.io/mcp/tools) (capability overview: [/mcp/tools](/mcp/tools)).

- **Sequences & multichannel outreach** — inspect email and LinkedIn sequences, their steps, A/B variants, and performance; launch, pause, and resume outreach; enroll and manage contacts; connect mailboxes, LinkedIn accounts, and schedules; switch Jason between review and autonomous modes.
- **Contacts & lists** — find, filter, create, and update contacts; review activity history; mark replies; reassign ownership; blacklist an address or a whole domain.
- **Unified inbox & conversations** — read threads with previews, send replies, and categorize conversations.
- **Jason AI SDR** — approve, reject, or regenerate drafts individually or in bulk; manage the knowledge bases, reply handlers, offers, playbooks, and reengagement that drive the autopilot.
- **Tasks** — list, create, and complete follow-up tasks.
- **Workspace & accounts** — resolve mailboxes and their limits, connected LinkedIn accounts, sending schedules, lists, and team members.
- **Help & navigation** — search the Reply Help Center, read articles, map the app, and report an unsupported request.

Read operations are safe; anything that sends or changes data is gated for confirmation first.

## The full technical reference lives on docs.reply.io

This page is the high-level surface map. For implementation details:

- **[Connect](https://docs.reply.io/mcp/connect)** — client configs, handshake, auth details, rate limits
- **[Tool contract & errors](https://docs.reply.io/mcp/tool-contract)** — schema rules, pagination,
  response envelopes, error codes, the safe-retry matrix
- **[Building agents](https://docs.reply.io/mcp/agent-guide)** — design principles, high-stakes
  gating, a drop-in system prompt
- **[Workflow recipes](https://docs.reply.io/guides/launch-outreach)** — launch a sequence safely, supervise
  Jason, reply to a thread, and more
- **[Tool reference](https://docs.reply.io/mcp/tools)** — the full toolset with per-argument documentation
- **[MCP overview](https://docs.reply.io/reply-mcp)** — the canonical at-a-glance page, generated from the live server

The always-current runtime source is the server itself: call `tools/list` and trust what it returns.

## FAQ

**Is the MCP server real, and how current is this page?**

Real and live. Endpoint https://mcp.reply.io/, MCP protocol 2025-06-18. The canonical, continuously maintained reference — auth, contract rules, envelopes, error model, full tool catalog — lives at docs.reply.io. The runtime truth is always tools/list on the live server.

**How does authentication work?**

Send your Reply.io API key as an `Authorization: Bearer <key>` header. That is the only key header this server accepts — there is no `x-api-key` fallback. Get a key in the Reply.io app under Settings → API Keys. No session header is required. A call with no credentials returns 401 with a `WWW-Authenticate` challenge, and OAuth protected-resource metadata is published for clients that prefer a discovery-based flow. Full details at [docs.reply.io/mcp/connect](https://docs.reply.io/mcp/connect).

**How do I know which tools are safe to call?**

The server tells you, machine-readably. Every tool carries MCP annotations — readOnlyHint or destructiveHint. Agents can auto-gate on them; anything that reaches a prospect or changes ownership should also get explicit user confirmation. The full contract and safe-retry matrix is at docs.reply.io.

**When should an agent use MCP instead of the REST API?**

Use MCP for interactive, natural-language work — the tools cover most day-to-day operations including the full Jason AI SDR autopilot. Use REST (api.reply.io/v3) for bulk imports, scheduled backend syncs, deep report exports, and anything tools/list does not expose.

**Is the Jason autopilot really callable here?**

Yes. The approval queue, the Review↔Autonomous switch, and the whole knowledge base / offer / playbook / reply-handler / reengagement-card surface are live MCP tools.