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.
https://api.tryreach.email/mcphttps://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/mcpinside Claude Code and choose Authenticate. Add--scope userto 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.
What consent looks like
Your browser opens the Reach consent page. You sign in if you are not already, choose the organisation and project the assistant will act on, and see the exact scopes it asks for. Nothing is granted until you approve.
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.
| Tool | Scope | Does | Mirrors |
|---|---|---|---|
list_tenants | tenants:read | List the tenants of the connected project. Start here: every other tool takes a tenant id. | GET /v1/tenants |
get_tenant | tenants:read | Read one tenant, with its status and send limits. | GET /v1/tenants/{id} |
create_domain | domains:write | Add a sending domain and get the DNS records to publish. | POST /v1/domains |
list_domains | domains:read | List a tenant's sending domains with their verification state. | GET /v1/domains |
get_domain | domains:read | Read a domain, its DNS records and what is missing. | GET /v1/domains/{id} |
send_email | emails:send | Send one transactional email. An idempotencyKey is required. | POST /v1/emails |
list_emails | emails:read | Query the email log: metadata and status, never message content. | GET /v1/emails |
get_email | emails:read | Read one email with its delivery events. | GET /v1/emails/{id} |
list_suppressions | suppressions:read | List suppressed addresses: why a recipient did not get mail. | GET /v1/suppressions |
list_webhook_deliveries | webhooks:read | Query webhook deliveries: did my webhook fail? | GET /v1/webhook-deliveries |
Start with list_tenants: every other tool takes a tenant id.
- Creating, updating or deleting a tenant
- Webhook subscriptions: creating, changing, rotating a secret
- Releasing a suppressed address
- Reading a single webhook delivery by id
These stay on the /v1 API and in the console.
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.
{
"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"
}idempotencyKeyis required (8 to 255 characters), scoped to the tenant. A repeat with the same key sends nothing and returns the original withreplayed: 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_suppressionsshows why.- A
429comes back as a tool error carryingretryAfterSeconds. Wait that long and retry with the same key.
// 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
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized, invalid_token | No valid MCP token. Not an error to fix by hand: the client reads the challenge, finds the authorization server and signs you in. |
| 403 | insufficient_scope | The 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 error | idempotency_key_reused | send_email was called with a key already used for a different recipient or subject. Use a new key for each new email. |
| tool error | rate_limited | A send limit was hit. The result carries retryAfterSeconds: wait that long, then retry with the same idempotencyKey. |
| tool error | not_found | The resource belongs to another organisation or project, or does not exist. Tools can only see the project you connected. |
| 422 | validation_failed | The input failed validation. Unknown fields are refused rather than dropped, so a filter you asked for is never silently ignored. |
| 405 | method_not_allowed | GET and DELETE on the endpoint, with an Allow: POST header. The server is stateless: only POST is accepted. |
// 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
emails:send or domains:write only when you want it to act.- 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.