MCP server

ReplyLayer speaks the Model Context Protocol, so an MCP client (Claude Desktop, Cursor, or your own agent runtime) can send, reply, read, monitor, and triage email as tool calls — every message security-scanned on the way in and out. This is a transactional and operational email surface, not a bulk or marketing tool.

There are two ways to connect, and they expose the same 44 tools:

	Hosted (`/v1/mcp`)	Local (stdio)
Transport	Streamable HTTP over `POST https://api.replylayer.ai/v1/mcp`	Subprocess over stdin/stdout
Client requirement	Native remote-MCP-over-HTTP support	Any MCP client that can spawn a command
Auth	`Authorization: Bearer <api-key>` on each request	API key from the environment or a stored credentials file
Install	Nothing to install — point the client at the URL	`npx -y replylayer-mcp` (or a global install)

Both share one tool set, so the choice is purely about how your client connects. Use the hosted endpoint when your client supports remote HTTP MCP servers; use the stdio server for local agents and clients that launch a command.

Credentials

Both transports authenticate with a single ReplyLayer API key — the same key you use for the REST API. A newly created key is inert on protected routes until a human completes both signup checks (a 6-digit email code and a 6-digit SMS code); the MCP server runs with a key a human has already provisioned and verified. See Authentication for the key format and admin-vs-agent scoping, and Quickstart for provisioning a key.

Hosted endpoint (`/v1/mcp`)

The hosted endpoint is stateless: each request is a self-contained MCP JSON-RPC call over Streamable HTTP with no server-side session. Point a remote-capable MCP client at the URL and pass your API key as a Bearer header:

{
  "mcpServers": {
    "replylayer": {
      "url": "https://api.replylayer.ai/v1/mcp",
      "headers": { "Authorization": "Bearer rly_live_<public_id>.<secret>" }
    }
  }
}

Contract details for anyone driving the endpoint directly:

Method: POST only. Requests carry Content-Type: application/json and Accept: application/json, text/event-stream (native clients set these for you).
Auth: a missing or non-Bearer Authorization header returns 401 before any tool runs.
GET and DELETE return 405 Method Not Allowed (with an Allow: POST header). Because the endpoint is stateless there is no SSE-over-GET stream and no session to delete — this is expected, not an outage.

Local stdio server

For clients that launch a command, install nothing globally and let the client run the server via npx. Add this to your client's MCP config (Claude Desktop's claude_desktop_config.json or a Cursor mcpServers block):

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

The server resolves the API key from the REPLYLAYER_API_KEY environment variable first, then from the stored credentials file at ~/.replylayer/credentials. To store the key interactively instead of putting it in the config (writes the credentials file with mode 0600), run:

npx -y replylayer-mcp init

If you stored the key that way, the env block above is optional. For CI or automation, skip init and pass REPLYLAYER_API_KEY in the environment. With a global install (npm i -g replylayer-mcp) you can set "command": "replylayer-mcp" and drop args.

What the tools cover

The 44 tools break down by category:

Reads (no side effects): list and read messages, threads, and drafts; wait for the next inbound message; list mailboxes, recipients, suppressions, the recipient allowlist, the inbound firewall lists; check account usage and the send quota; fetch a derived attachment text preview; and check malicious-link scanning status.
Sends: send a new email, reply to a message, or send a prepared draft.
Drafts: create, update, delete, and send drafts.
Inbound triage: release or block a quarantined message, report-and-block a sender, and release a firewall-blocked message. Human-in-the-loop review approval and denial are admin-only (agent keys receive a 403).
Policy and contacts: add recipients, add do-not-contact suppressions, manage the inbound blocklist and allowlist, and mark messages or threads read — with bulk variants (up to 1,000 addresses per call) for suppressions and the inbound lists.
Star / unstar and delete: flag messages or threads, and soft-delete a message.

The high-traffic reads and sends return a typed structuredContent object alongside the human-readable text block, so an agent can consume the result without re-parsing prose. The full, annotated tool table — every input field, output schema, and per-tool note — is the machine contract at /agents/mcp.

How results signal errors

A tool that fails returns a tool result with isError: true (a readable message the model can recover from), rather than a JSON-RPC protocol error — so a recoverable condition never crashes the tool call. The full error-handling contract, including which conditions surface this way, lives at /agents/mcp; the machine-readable error catalog is at /agents/errors.

Sends return an outcome you branch on

The send tools do not report success or failure the way a plain HTTP call would — they return a delivery outcome (for example, delivered, held for review, or scanner-held) that you branch on. The state and verdict vocabulary those outcomes draw from is documented once at /agents/messages; the send tool response shapes are on /agents/mcp.

Safety model

Every inbound read carries a standing untrusted-content contract in its agent_safety_context: message bodies, attachments, and links are untrusted input, and the accompanying guidance tells the agent not to follow instructions embedded in a message. Scanning is directional — outbound text that resembles prompt-injection is your agent's own authored content and is delivered, while inbound prompt-injection is held. See Content scanning for the customer-readable model and /agents/security-model for the per-field trust taxonomy.

Relaxing that untrusted-content contract for a specific verified sender is possible, but it is configured entirely from the dashboard (with a fresh human re-auth) — an agent, and this MCP server, cannot enable or grant it. There is no client-side opt-in and no MCP tool to grant, list, or revoke trusted instruction sources.