Give Claude or Cursor an email inbox over MCP
Give Claude or Cursor an email inbox over MCP ReceiveHQ can give a coding agent a real inbound mailbox: a domain you control, MX at mx.receivehq.com, and MCP tools to create the domain, check DNS, and read messages. Th
Give Claude or Cursor an email inbox over MCP
ReceiveHQ can give a coding agent a real inbound mailbox: a domain you control, MX at mx.receivehq.com, and MCP tools to create the domain, check DNS, and read messages. The MCP server URL is https://receivehq.com/api/mcp.
This is not a sending API. Outbound mail is out of scope.
1. What you get
Authentication is OAuth 2.1 with PKCE and Dynamic Client Registration. Scopes: mcp:read (read tools) and mcp:admin (create, update, delete, resend, checkout). Cursor can register itself; you approve access with the magic-link login ReceiveHQ already uses.
endpointKind on setup tools is:
-
blackhole— store the message only (typical for an agent inbox); delivery statusblackholed; no HTTP forward -
webhook— also POST to your HTTPS URL
Useful tools (names and arguments from the live MCP server schemas):
| Tool | Role | Arguments |
|---|---|---|
list_tenants |
List tenants you can access | none |
create_tenant |
Create a tenant |
name (required), optional domains
|
setup_inbound_domain |
Wizard: optional domain + first endpoint + MX verify |
tenantId (required); primaryDomain or inboundDomainId; endpointKind (webhook \ |
create_inbound_domain |
Create a domain only |
tenantId, primaryDomain
|
create_inbound_domain_endpoint |
Add an endpoint to a domain |
tenantId, domainId, name; optional endpointKind, url, enabled, toAddressFilter, maxAttempts, payloadFormat, basicAuthUser, basicAuthPass, sortOrder
|
update_endpoint |
Update an endpoint, including switching webhook ↔ blackhole
|
tenantId, endpointId; optional name, endpointKind, url, filters, maxAttempts, payloadFormat, Basic auth fields. url is cleared when switching to blackhole. |
verify_inbound_domain_mx |
Re-check MX for a domain |
tenantId, domainId
|
list_messages |
List inbound messages |
tenantId; optional status, q, limit (max 200), offset
|
get_message |
One message plus delivery summary |
tenantId, messageId
|
list_deliveries |
Webhook attempts or blackholed store-only routes |
tenantId, messageId
|
You need mcp:admin to create a domain or endpoint, and mcp:read to list mail.
2. Connect Cursor
In Cursor's MCP config (mcp.json), add the official URL:
{
"mcpServers": {
"receivehq": {
"url": "https://receivehq.com/api/mcp"
}
}
}
After a reload, Cursor should run OAuth (PKCE + DCR) and open the ReceiveHQ login. Approve read for listing mail; approve admin to create a domain. Revoke connected apps later under Settings → MCP in the console.
3. Connect Claude
Use the same server URL, https://receivehq.com/api/mcp, in Claude Desktop or any other OAuth MCP client — that is the config ReceiveHQ documents for both Cursor and Claude. The client discovers OAuth, registers if needed, and opens a browser for magic-link login and consent.
4. Create the inbox
Once the server is connected, ask the agent (in your words) to:
- List or create a tenant (
list_tenants/create_tenant).setup_inbound_domainneeds atenantId. - Run
setup_inbound_domainwithendpointKindblackholeif you only want the agent to read mail (omitendpointUrl). For a webhook, also passendpointUrlandpayloadFormat. - Show the MX target:
mx.receivehq.com. - You add the MX at your DNS host. This is the step a local agent cannot do for you.
- Call
verify_inbound_domain_mxwith thattenantIdanddomainId. - Send a test message to an address on that domain.
- Call
list_messages(optionalq,status,limit,offset), thenget_messagefor the body.list_deliveriesshows webhook attempts, or statusblackholedfor a store-only endpoint.
You can also create the domain first (create_inbound_domain) and add the endpoint with create_inbound_domain_endpoint. A blackhole endpoint can later become a webhook with update_endpoint (endpointKind: "webhook" plus an HTTPS url); switching the other way clears the URL.
5. payloadFormat if you also attach a webhook
Format ids are: postmark (JSON, default), mailgun_sendgrid (multipart; underscore), cloudmailin, inbound, emailconnect, and mailslurp. Use mailgun_sendgrid when you want the Mailgun/SendGrid multipart body — that is the id in the Webhook API docs and in the MCP create_endpoint / create_inbound_domain_endpoint schemas.
6. Limits
- Trial: first 10 emails free, up to 3 trial tenants; then the tenant is locked until you subscribe. Paid plan on receivehq.com: €10/month or €100/year for 100,000 inbound emails, then €10 per additional 100,000.
- The public DPA states a 14-day retention window for raw mail and delivery-log objects, unless agreed otherwise.
Further reading
To give Cursor or Claude a real inbound mailbox, connect ReceiveHQ at https://receivehq.com/api/mcp and point MX at mx.receivehq.com.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.