Dev.to WebDev 🛠 Dev 👁 0 📖 3 min read

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 status blackholed; 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:

  1. List or create a tenant (list_tenants / create_tenant). setup_inbound_domain needs a tenantId.
  2. Run setup_inbound_domain with endpointKind blackhole if you only want the agent to read mail (omit endpointUrl). For a webhook, also pass endpointUrl and payloadFormat.
  3. Show the MX target: mx.receivehq.com.
  4. You add the MX at your DNS host. This is the step a local agent cannot do for you.
  5. Call verify_inbound_domain_mx with that tenantId and domainId.
  6. Send a test message to an address on that domain.
  7. Call list_messages (optional q, status, limit, offset), then get_message for the body. list_deliveries shows webhook attempts, or status blackholed for 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.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.