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.
• 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. 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 (they return 405 with an Allow: POST header). Authenticate every request with Authorization: Bearer <api-key>; a missing or malformed Bearer token returns 401.

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:

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

Only 10 of the 44 tools declare an outputSchema, and only those also emit structuredContent (a machine-parseable object) alongside the text block. The other 34 return their JSON as text content only — parse content[0].text.

Tools with a declared output schema + structuredContent:

send_email, reply_to_message, send_draft, list_messages, read_message, get_thread, list_threads, list_mailboxes, wait_for_message, get_attachment_preview.

This is intentional and uneven: several read-only tools (for example list_suppressions, list_allowlist, list_recipients, get_draft, get_account_usage, get_agent_quota) return text-only JSON despite being pure reads. Do not assume a read tool emits structuredContent — check for the tool in the list above, and otherwise parse the text block.

Server instructions differ by transport

The stdio server ships a server-level instructions primer — 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 hosted /v1/mcp server does not currently send server instructions. A host connecting over hosted HTTP will not receive that primer and should rely on the per-tool description fields, which are self-contained. This is current behavior — plan for it rather than assuming the primer is present on hosted.

Tool registry (44 tools)

Tools marked † declare an outputSchema and emit structuredContent; all others return text-only JSON. The Annotations column lists the MCP hints each tool declares (readOnly, destructive, idempotent, openWorld); a — means no hint is declared. 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.