# ReceiveHQ MCP

> Connect AI agents (Cursor, Claude, etc.) to ReceiveHQ over Model Context Protocol — configure domains, create blackhole or webhook endpoints, receive and manage mail, and handle billing with OAuth. Agent-native: the full account lifecycle without the console.

## Quick connect

1. Create a ReceiveHQ account at [https://receivehq.com/](https://receivehq.com/) (magic-link email sign-in).
2. Add the MCP server URL to your client:

```json
{
  "mcpServers": {
    "receivehq": {
      "url": "https://receivehq.com/api/mcp"
    }
  }
}
```

3. Start the client — it will open a browser for login and consent.
4. Revoke apps anytime under **Settings → MCP** in the console.

## Endpoints

| Path | Role |
| --- | --- |
| `GET/POST/DELETE /api/mcp` | Streamable HTTP MCP resource (Bearer token) |
| `GET /.well-known/mcp` | Discovery manifest (SEP-1960-style) |
| `GET /.well-known/mcp/server-card.json` | Server card (SEP-1649-style) |
| `GET /.well-known/oauth-protected-resource/api/mcp` | RFC 9728 PRM |
| `GET /.well-known/oauth-authorization-server` | RFC 8414 AS metadata |
| `POST /api/mcp/oauth/register` | Dynamic client registration |
| `GET /api/mcp/oauth/authorize` | Browser authorize → consent UI |

## Scopes

- `mcp:read` — read tools
- `mcp:admin` — mutating tools (create/update/delete, resend, checkout)

Tokens are **user-scoped** (all of that user’s tenants). Tools take `tenantId` and re-check membership on every call.

## What agents can do

- Tenants: list / get / create / update / delete
- Inbound domains: CRUD + MX verify + `setup_inbound_domain` wizard
- Domain endpoints: `list_inbound_domain_endpoints`, `create_inbound_domain_endpoint`
- Tenant endpoints: `list_endpoints`, `get_endpoint`, `create_endpoint`, `update_endpoint`, `delete_endpoint`
- Messages: list / get / deliveries / resend
- Members & invitations
- Billing: status, Stripe Checkout URL, Customer Portal URL
- Logs: fetch retained attempt / raw-mail objects by key

## Endpoint kinds (webhook vs blackhole)

Every route on an inbound domain has `endpointKind`:

| Kind | `url` | Behavior |
| --- | --- | --- |
| `webhook` | Required HTTPS URL | POST parsed mail (Postmark / Mailgun-SendGrid / CloudMailin format) |
| `blackhole` | Omit / empty | Receive, parse, log; delivery status `blackholed`; no HTTP forward; works on trial |

**Agent quick start (blackhole):**

1. `setup_inbound_domain` with `endpointKind: "blackhole"` (no `endpointUrl`) — or `create_inbound_domain` then `create_inbound_domain_endpoint`.
2. User points MX to `mx.receivehq.com`; call `verify_inbound_domain_mx`.
3. `list_messages` / `get_message` / `list_deliveries` to read captured mail.

**Webhook example:** `create_inbound_domain_endpoint` with `endpointKind: "webhook"`, `url`, and `payloadFormat: "postmark"`.

## Pricing reminder

€10/month or €100/year · 100k inbound emails · then €10 per additional 100k · first 10 emails free (trial). Hosted in Germany.

## Related

- [llms.txt](https://receivehq.com/llms.txt) — site index for LLMs
- [Webhook API docs](https://receivehq.com/docs)
- [security.txt](https://receivehq.com/.well-known/security.txt)