MCP server (Claude, Cursor)

Let an AI assistant work in your Reach project: onboard a sending domain, send email and find out why something did not arrive. You sign in and choose the scopes; no API key is involved.

What it is

Reach runs a remote Model Context Protocol server at https://api.tryreach.email/mcp (Streamable HTTP). It exposes 10 tools that call the same services as the /v1 API, with the same validation, limits and tenant isolation.

  • OAuth only. API keys are not accepted here, and an MCP token is not accepted on /v1.
  • One organisation and project. You choose them when you approve the connection. No tool takes an organisation or project argument.
  • Nothing destructive. No tool deletes or releases anything. Message content is never returned: only metadata and status.

Connect a client

Every client needs only the URL. It discovers the rest from the 401 the server returns to an unauthenticated request, opens the Reach consent page in your browser, and receives a token once you approve.

MCP server URL
https://api.tryreach.email/mcp
Connect a client (Claude)
https://api.tryreach.email/mcp
  • Claude. Open Customize, then Connectors, then Add, then Add custom connector. Enter a name and paste the URL. On Team and Enterprise plans an owner adds the connector first.
  • Claude Code. Run claude mcp add --transport http reach https://api.tryreach.email/mcp, then run /mcp inside Claude Code and choose Authenticate. Add --scope user to make it available in every project.
  • Cursor. Put the entry in .cursor/mcp.json (this project) or ~/.cursor/mcp.json (everywhere), then sign in when Cursor asks.

The same URL works in any MCP client that supports remote servers with OAuth. In the console, the same snippets are on the Organisation page.

Tools and scopes

Each tool needs one scope. If your grant does not include it, the server answers 403 insufficient_scope naming the scope, and the client sends you back to approve again with it added (step-up). The scopes the tools use are: tenants:read, domains:write, domains:read, emails:send, emails:read, suppressions:read, webhooks:read.

MCP tools, the scope each needs and the /v1 route it mirrors
ToolScopeDoesMirrors
list_tenantstenants:readList the tenants of the connected project. Start here: every other tool takes a tenant id.GET /v1/tenants
get_tenanttenants:readRead one tenant, with its status and send limits.GET /v1/tenants/{id}
create_domaindomains:writeAdd a sending domain and get the DNS records to publish.POST /v1/domains
list_domainsdomains:readList a tenant's sending domains with their verification state.GET /v1/domains
get_domaindomains:readRead a domain, its DNS records and what is missing.GET /v1/domains/{id}
send_emailemails:sendSend one transactional email. An idempotencyKey is required.POST /v1/emails
list_emailsemails:readQuery the email log: metadata and status, never message content.GET /v1/emails
get_emailemails:readRead one email with its delivery events.GET /v1/emails/{id}
list_suppressionssuppressions:readList suppressed addresses: why a recipient did not get mail.GET /v1/suppressions
list_webhook_deliverieswebhooks:readQuery webhook deliveries: did my webhook fail?GET /v1/webhook-deliveries

Start with list_tenants: every other tool takes a tenant id.

Sending email

send_email takes one recipient per call and returns as soon as the email is recorded. The from domain must be a verified domain of the tenant.

send_email input
{
  "tenant": "tn_9f8c2a1d",
  "from": "billing@acme.com",
  "to": "customer@example.com",
  "subject": "Your invoice is ready",
  "html": "<p>Hi, your invoice for September is ready.</p>",
  "idempotencyKey": "invoice-2026-09-cust_8f2e1a"
}
  • idempotencyKey is required (8 to 255 characters), scoped to the tenant. A repeat with the same key sends nothing and returns the original with replayed: true, so an assistant can retry safely.
  • Reusing a key for a different recipient or subject is refused with idempotency_key_reused, never silently replayed. Use a new key per new email.
  • held: while your organisation's first send is under review, the email is accepted and recorded but not sent. It is not an error and nothing is lost. It goes out once the organisation is approved: do not retry with a new key.
  • suppressed: the recipient is on the tenant's suppression list after a bounce or complaint, so nothing was sent. Not an error. list_suppressions shows why.
  • A 429 comes back as a tool error carrying retryAfterSeconds. Wait that long and retry with the same key.
send_email results
// Accepted: delivery happens afterwards, so read get_email for the outcome.
{ "id": "em_5b1e7c40", "status": "queued", "tenant": "tn_9f8c2a1d", "acceptedAt": "...", "replayed": false }

// Same key, same email: nothing is sent again, the original is returned.
{ "id": "em_5b1e7c40", "status": "queued", "replayed": true, "replayNote": "..." }

// First send of a new organisation: recorded, not sent yet. Not an error.
{ "id": "em_5b1e7c41", "status": "held", "explanation": "..." }

// Recipient is on the suppression list: nothing sent. Not an error.
{ "id": "em_5b1e7c42", "status": "suppressed", "explanation": "..." }

Errors

Errors from the MCP endpoint
StatusCodeMeaning
401unauthorized, invalid_tokenNo valid MCP token. Not an error to fix by hand: the client reads the challenge, finds the authorization server and signs you in.
403insufficient_scopeThe token lacks the scope the tool needs, and the response names it. The client asks you to approve again with that scope added (step-up).
tool erroridempotency_key_reusedsend_email was called with a key already used for a different recipient or subject. Use a new key for each new email.
tool errorrate_limitedA send limit was hit. The result carries retryAfterSeconds: wait that long, then retry with the same idempotencyKey.
tool errornot_foundThe resource belongs to another organisation or project, or does not exist. Tools can only see the project you connected.
422validation_failedThe input failed validation. Unknown fields are refused rather than dropped, so a filter you asked for is never silently ignored.
405method_not_allowedGET and DELETE on the endpoint, with an Allow: POST header. The server is stateless: only POST is accepted.
Tool error shape
// A tool error: isError is true and the structured content carries the code.
{ "code": "rate_limited", "message": "...", "details": [ ... ], "retryAfterSeconds": 12 }
{ "code": "idempotency_key_reused", "message": "...", "details": [ { "field": "subject", "reason": "differs_from_original" } ] }

The general error format and rate limits are described in Errors and rate limits.

Revoking access

Open Organisation, then Connected apps, and disconnect the app. It stops working on its next request. To give it different scopes, disconnect it and connect again, or approve a new request: approving again replaces the earlier grant.

Security

  • No tool can delete anything, and a send needs an idempotency key.
  • A new organisation's first send is held for review, whoever triggers it.
  • Check the host on the consent page: the app is unverified.
  • Disconnect apps you no longer use.