Hosted MCP server

Mailcrate runs an MCP server at:

https://mcp.mailcrate.io/mcp

Point an agent at it and it can work your workspace — look up contacts, check why a delivery bounced, render a template, send a transactional email. Nothing to install and nothing to run.

If your agent runs on your own machine and can start a local process, the CLI's mailcrate mcp does the same job over stdio and keeps the key on your machine. This page is for the agents that cannot: the claude.ai web and desktop clients, Managed Agents, and other hosted platforms.

AuthenticationCopy Anchor Link

Two ways in, and the server treats them identically once the credential arrives. OAuth is the one to reach for if your client offers it; a workspace API key works everywhere and is the right answer for CI and for anything running unattended.

Either way the server stores nothing — no accounts, no sessions, no key material. It forwards your credential to the Mailcrate public API on each request, and that is what authenticates it, applies its scopes, and binds every call to one workspace. A credential the API rejects comes back to your agent as the API's own 401.

OAuthCopy Anchor Link

If your client supports OAuth, there is nothing to paste and nothing to copy. Point it at https://mcp.mailcrate.io/mcp, and it will discover the rest:

1. The server answers an unauthenticated request with a 401 whose WWW-Authenticate names its protected-resource metadata at https://mcp.mailcrate.io/.well-known/oauth-protected-resource/mcp — the resource-suffixed spelling the MCP SDK constructs. The bare /.well-known/oauth-protected-resource serves the same document, so a client following either convention finds it.
2. That document points at the authorization server, https://api.mailcrate.io, whose own metadata lives at /.well-known/oauth-authorization-server.
3. Your client registers itself (RFC 7591) and sends you to Mailcrate to approve it.
4. You log in, choose which workspace the application may act in, review the permissions it asked for, and approve.

You end up with a short-lived access token — one hour, refreshed automatically — scoped to one workspace and to the permissions on that screen.

Two things worth knowing before you approve:

• The application's name is self-asserted. It chose that name when it registered, and anyone can register one. The line the consent screen shows underneath it — the host your browser will be redirected back to — is the part nobody can fake without also controlling that host. Read that one.
• Connecting an application needs the owner or admin role, the same role that can mint an API key. A grant produces a credential for the whole workspace, so it is gated like one.

full_access is not available over OAuth at all. An application must name the permissions it wants, and the consent screen lists every one of them. A client that asks for no permissions at all gets read-only access.

Manage what you have approved under Settings → Connected Applications. Disconnecting revokes the access token and the refresh token together, and takes effect on the application's very next request.

Workspace API keyCopy Anchor Link

Send the key as a bearer token:

Authorization: Bearer <api_key>

Connect from claude.aiCopy Anchor Link

Settings → Connectors → Add custom connector. If the dialog offers OAuth, give it the URL alone and approve the consent screen it opens. Otherwise:

Connect from ChatGPTCopy Anchor Link

Add it as a connector pointing at https://mcp.mailcrate.io/mcp. ChatGPT requires OAuth and will not accept a pasted key, so it runs the discovery flow above: it registers itself and sends you to Mailcrate to choose a workspace and approve. Nothing to configure beyond the URL.

Connect from Claude CodeCopy Anchor Link

claude mcp add mailcrate \
  --transport http https://mcp.mailcrate.io/mcp \
  --header "Authorization: Bearer <api_key>"

Connect from Managed AgentsCopy Anchor Link

Store the key in the agent's vault as a static_bearer MCP credential pointing at https://mcp.mailcrate.io/mcp. An unattended agent is exactly the case a key suits better than OAuth — there is nobody to approve a consent screen.

Testing it by handCopy Anchor Link

Worth knowing before you reach for curl: the endpoint requires an Accept header listing both application/json and text/event-stream. That is the Streamable HTTP transport's own rule, and it is strict — Accept: */* is rejected too, which is not what most people expect.

curl -sS https://mcp.mailcrate.io/mcp \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }'

MCP clients set this for you; it only bites when testing by hand.

Which key to give an agentCopy Anchor Link

The key is the real boundary — not the tool list, which is the same for everyone. A read-only key still shows the write tools; the API simply refuses them with a 403 naming the missing scope, which the agent sees verbatim and can explain to you.

• Exploring, reporting, drafting — a read-only key: the :read scopes for the areas the agent should see (contact:read, campaign:read, delivery:read, email-template:read).
• Sending — add only the write scope you mean, such as sending:write for transactional mail.
• full_access — only for an integration you fully trust. It bypasses every per-resource check, which is why it cannot be granted over OAuth: a consent screen offering it would be asking you to approve everything, forever.

See API Keys & Scopes for the full list. The same scopes are what an OAuth consent screen lists, in plain words rather than identifiers.

What the agent can doCopy Anchor Link

The same curated tool set as the CLI, minus anything that reads files from the machine the server runs on — push is available only over the local stdio server, because here that machine is ours rather than yours.

It also has the two documentation tools, search_docs and get_doc_page, so an agent can look up an endpoint or an error while it works. They never call the API. To use them without a workspace key, connect to https://mcp.mailcrate.io/docs instead, which serves only those two and needs no credential. See Docs for AI Agents.

Tools carry readOnlyHint and destructiveHint annotations, and anything that sends mail also requires an explicit confirm: true argument, so a model cannot send on your behalf without saying that it meant to. See Irreversible tools.

Limits and behaviourCopy Anchor Link

• Rate limits are your key's, applied by the public API — the same budget the REST API uses. A 429 reaches the agent with retryAfterSeconds, so it can back off rather than hammer. See Rate limits.
• Request bodies are capped at 1 MiB.
• Upstream calls time out after 30 seconds.
• Long values are truncated. A single value over 20,000 characters — in practice a rendered email — is cut with a …[truncated] marker and a note.
• Statelessness. The server issues no session id and holds nothing between requests, so it runs behind an ordinary load balancer. Your client does not need sticky sessions, and a dropped connection costs nothing but a retry.

TroubleshootingCopy Anchor Link

406 Not Acceptable — your Accept header does not list both application/json and text/event-stream. Sending only one of them, or */*, or omitting the header entirely, all get a 406. See Testing it by hand. Real MCP clients set this themselves, so this is almost always a hand-written request.

"Missing bearer token" — the request arrived with no Authorization header. Some clients do not forward one unless it is configured in the connector itself.

401 Invalid API Key — the key was forwarded but the API rejected it. Check it has not been revoked, and that you copied the whole thing.

401 Invalid or expired access token — an OAuth token that has expired, been revoked, or belongs to a workspace that no longer exists. A client that handles refresh will recover on its own; if it keeps happening, the grant was probably disconnected under Settings → Connected Applications and the application needs approving again.

Your client will not start an OAuth flow — it either does not support OAuth (use a key) or it could not read the WWW-Authenticate challenge. Confirm discovery is reachable:

curl -sS https://mcp.mailcrate.io/.well-known/oauth-protected-resource

403 API key is missing required scope "…" — the key works; it is not allowed to do that. Grant the scope, or point the agent at something else.

A tool is missing — push is stdio-only by design. Everything else should be present; check with your client's tool list.