MCP server

ReplyLayer ships a Model Context Protocol (MCP) server so an agent host can call the platform as tools instead of raw HTTP. The same tool registry backs two transports, so the tool set, names, and behavior are identical either way:

• Hosted — a streamable-HTTP endpoint at POST /v1/mcp on the API. No install; authenticate with your API key as a Bearer token. Claude, ChatGPT and Meta Muse instead sign in (OAuth) at POST /v1/mcp/oauth, the same handler listing every tool except the four an agent key can never use (see below).
• stdio — the replylayer-mcp package (npm), run locally as a subprocess by your MCP client. Reads the API key from the environment or stored credentials.

Both expose the same 44 tools; a sign-in connection lists 40 of them. Every tool call returns an MCP CallToolResult; on failure the result carries isError: true and a structured JSON envelope you branch on (see The result envelope).

Connect over hosted HTTP

The hosted server is stateless: every POST /v1/mcp request is independent — there is no session id, and GET/DELETE are not supported (with a valid key they return 405 with an Allow: POST header; without one, 401). Authenticate every request with Authorization: Bearer <api-key>; a missing or malformed Bearer token returns 401. Authentication on /v1/mcp is a static Bearer key; this URL has no OAuth flow and no OAuth discovery metadata.

Sign-in endpoint (/v1/mcp/oauth). The same stateless handler and tool set, authenticated by OAuth 2.1 for three clients only: Claude, ChatGPT and Meta Muse. Without a token it answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.replylayer.ai/.well-known/oauth-protected-resource/v1/mcp/oauth", scope="mailboxes", which starts the client's sign-in. Each connection acts as an agent key bound to the mailboxes the user approved, so every agent-key limit applies, and tools/list leaves out the four tools an agent key can never use: approve_review, deny_review, get_account_usage and remove_suppression. Every tool listed there carries securitySchemes (oauth2, scope mailboxes), top-level and mirrored in _meta, and a tool error caused by the token being revoked or expiring mid-request carries _meta["mcp/www_authenticate"]: the same error="invalid_token" challenge plus error_description="The ReplyLayer connection is no longer valid; sign in again", so a client that signs in per tool can send the user back through sign-in; /v1/mcp carries neither. The two URLs never share credentials: an API key is refused on /v1/mcp/oauth, and an OAuth token is refused on /v1/mcp and every REST route. Access tokens last one hour; a connection ends after 30 days without use and at the latest 90 days after consent, and the user can revoke it from the dashboard at any time. The human-facing setup is in MCP server.

A representative MCP client config:

{
  "mcpServers": {
    "replylayer": {
      "type": "streamable-http",
      "url": "https://api.replylayer.ai/v1/mcp",
      "headers": { "Authorization": "Bearer rly_live_..." }
    }
  }
}

The hosted server does no implicit retry. If the API returns a rate-limit or transient error, the structured error is surfaced to your tool result immediately rather than the server sleeping through a Retry-After. Your agent owns the retry decision — read details.retry_after / details.reset_at and decide (see Errors).

Connect over stdio

Run the published replylayer-mcp package as a subprocess. It resolves the API key from REPLYLAYER_API_KEY, or from credentials stored by replylayer-mcp init (written under ~/.replylayer/). REPLYLAYER_API_URL optionally overrides the API base (defaults to the public API).

{
  "mcpServers": {
    "replylayer": {
      "command": "npx",
      "args": ["-y", "replylayer-mcp"],
      "env": { "REPLYLAYER_API_KEY": "rly_live_..." }
    }
  }
}

Like the hosted transport, the stdio server does no implicit retry — a tool call fails fast and returns the structured error so the agent decides retry-vs-abort.

The result envelope

Every tool returns an MCP CallToolResult. On success, content[0].text is the tool's JSON result (pretty-printed). On failure, isError: true and content[0].text is a JSON string with this shape:

{
  "error": "human-readable message",
  "code": "STABLE_ERROR_CODE",
  "details": { "...": "structured fields, when present" },
  "hint": ["next-step line", "..."]
}

Branch on code, not on the prose in error:

• code is the stable machine-readable error code. The full catalog lives in Errors.
• details carries structured fields when the API provides them — e.g. a rate-limit error carries daily_limit, sends_remaining, and reset_at; a capability/denial error carries reason_axis and a cheapest_next_step.
• hint is an array of plain-text next-step lines (the same guidance the CLI prints). It is advisory; the machine contract is code + details.

Tool-side precondition failures (for example a capability probe that shows the server cannot honor a has_attachment filter → SEARCH_OPERATOR_UNSUPPORTED) use the same { error, code, details? } envelope, so you branch on code uniformly whether the failure came from the API or from the tool itself.

Send tools return isError on a resolved send

send_email, reply_to_message, and send_draft can return isError: true even when the HTTP call succeeded — because a send the scanner refused, or one held by an infrastructure fault, is a failed tool call your host must not mark done. The flag is derived from the governed email-effect on the send result:

A held_for_review result leads with a HELD FOR REVIEW — not sent line (HELD — not sent for a quarantined send) that tells the agent to tell the account owner (the person it acts for) the email is waiting for their approval, with the direct link from hold_context.review_url and the deadline from hold_context.review_expires_at when the server has them, and not to send it again. An infrastructure hold never gets that line or the link: it is a failed call whose advice is to retry later. send_draft shapes its result the same way as send_email and reply_to_message.

An unrecognized or future effect_status fails closed to isError: true — an older server must not report an outcome it cannot interpret as success. For what each effect status means and how holds resolve, see Send gates. send_draft additionally surfaces its send-time conflicts (rescan rejection, already-sent) as isError JSON keyed on code, with the API details flattened to the JSON root.

Structured output

From replylayer-mcp 0.14.0, every tool except remove_suppression declares an outputSchema and returns structuredContent (a machine-parseable object) alongside the text block. The hosted endpoints (/v1/mcp, /v1/mcp/oauth) serve it once the server is updated; a local server has it from 0.14.0. remove_suppression always returns isError, so it has no success shape, and it is not listed on /v1/mcp/oauth. Earlier versions declare an output schema only on send_email, reply_to_message, send_draft, list_messages, read_message, get_thread, list_threads, list_mailboxes, wait_for_message and get_attachment_preview. Check the tool's outputSchema in tools/list; when a tool has none, parse the text block.

• structuredContent is the same JSON as the text block (for a held send, the text block after the leading HELD line).
• Each schema follows the API route's response, after the fields the tool leaves out (below). Objects accept fields the API adds later, enum-like values are declared as strings (known values are in the field description), and only the top-level fields the route always returns are required.
• A tool error (isError: true) carries no structuredContent, except a blocked or infrastructure-held send, which keeps its send result so you can read email_effect.
• Send results and message reads describe hold_context.review_url and hold_context.review_expires_at on a held send.

Fields MCP results leave out

MCP results carry what an assistant needs to act, not internal bookkeeping. On every transport (stdio, /v1/mcp and /v1/mcp/oauth) the tools remove these fields from the API response before building both the text block and structuredContent. The REST API, the SDKs and the CLI still return them.

The do-not-contact and inbound-blocklist source field names no vendor on MCP: a bounce or complaint delivered by the sending provider reads provider_webhook, an address found on the provider's own suppression list at send time reads provider_sync, and any value the server does not recognise reads system. customer, one_click_https and mailto_inbound are unchanged, and reason still says why the entry exists.

A 400 VALIDATION_ERROR keeps details.validation, but each item carries only instancePath (the field) and message. The top-level error already names the first failing field and, for an enum, its allowed values. A 500 SELF_HOSTED_DECRYPT_FAILED keeps details.endpoint (your mail host) and leaves out details.domain_id.

next_cursor on the list tools is an opaque paging token: pass it back unchanged as cursor and do not parse it or show it to a user.

list_drafts returns has_more beside drafts; when it is true, pass the last draft's id as before for the next page.

Server instructions

Both transports send the same server-level instructions primer: the stdio server and the hosted /v1/mcp server. It is a short workflow guide (branch on message status, recovery paths for held mail, how to read a rate-limit error) that a host can inject into the model context at connect time. The sign-in endpoint /v1/mcp/oauth sends the same primer with its API-key wording reworded for a connection: there is no API key, a revoked or expired connection means asking the user to reconnect, and the note on held-for-review mail says the connection (not an agent key) cannot approve. For held mail the primer tells the model to tell the account owner the send is waiting for them, give them hold_context.review_url, and not send it again.

Some hosts ignore server instructions (Hermes does), so do not depend on the primer being in context. The per-tool description fields are self-contained and carry what a model needs to call each tool correctly.

Tool registry (44 tools)

From replylayer-mcp 0.14.0, every tool except remove_suppression declares an outputSchema and emits structuredContent (see Structured output). Every tool declares a Title and explicit boolean readOnlyHint, destructiveHint and openWorldHint annotations, plus idempotentHint on every tool that changes something; the Annotations column lists the hints that are true. One tools/list serves every client, so where client guidelines differ the stricter reading wins: a tool that modifies account data is destructive even when it can be undone (the list and marker writes), and a tool that can email someone outside the account is openWorld. Annotations are advisory metadata for the host — the authoritative permission gates are enforced server-side.

Messages & threads

Mailboxes & account

Drafts & scheduled send

Recipients

Do-not-contact list

Suppression removal is a per-human admin decision by design. See the Do-not-contact guide for the full add / list / remove contract.

Recipient allowlist (outbound)

Inbound firewall

Triage & review

Where contracts live

This page owns the MCP transport, tool registry, and result-envelope contract. For the platform contracts a tool references, see the owning page:

• Message states, read semantics, and verdict vocabulary → Messages
• What happens when a send is held, blocked, or contained → Send gates
• Full error-code catalog → Errors
• Attachment staging and preview lifecycle → Attachments
• Tier and sandbox send limits → Limits
• Per-field trust and untrusted-content handling → Security model
• Webhook event catalog (dispatch, review, schedule signals) → Webhooks
• CLI equivalents and exit codes → CLI

The replylayer-mcp package is published on npm.