mcp-server

MCP (Model Context Protocol) server exposing the MinuteMail public API as tools. It lets AI agents and MCP clients operate MinuteMail mailboxes, emails, attachments, domains, teams, and mock OAuth identities through the mm-api-gateway.

• Endpoint: https://mcp.minutemail.co/mcp (Streamable HTTP, protocol revision 2025-06-18)

• Auth: the MCP client's Authorization: Bearer mmak_... header is forwarded verbatim to the api-gateway — this server holds no credentials. Scopes and quotas are enforced by the gateway exactly as for any API client.

• Stateless: no sessions, no server-push SSE (GET /mcp and DELETE /mcp return 405). Health: GET /health.

Tool surface (39 tools)

Every tool maps 1:1 to a /v1 route of the api-gateway. All calls require the Bearer API key; write operations require the matching scope (mailboxes, domains, team, identities).

Mailboxes (mailboxes scope)

Archived mailboxes (mailboxes scope)

mm_list_archived_mailboxes, mm_get_archived_mailbox, mm_delete_archived_mailbox, mm_reactivate_archived_mailbox.

Domains (domains scope)

mm_list_domains, mm_register_domain, mm_verify_domain, mm_delete_domain.

Team (team scope)

mm_list_members, mm_add_member, mm_get_member, mm_delete_member, mm_create_invitation, mm_list_invitations, mm_delete_invitation.

Mock identities (identities scope)

mm_list_identities, mm_create_identity, mm_get_identity, mm_delete_identity, mm_list_oauth_clients, mm_create_oauth_client, mm_get_oauth_client, mm_delete_oauth_client, mm_rotate_client_secret.

Not exposed

• /v1/api-keys CRUD — API-key management is not exposed via MCP; manage keys from the web app instead.

• /internal/* — internal-only. /metrics serves Prometheus metrics (runtime go_*/process_* counters) for scraping; see METRICS.md.

Related MCP server: SandMail — Disposable Email API for AI Agents

Example

curl -s https://mcp.minutemail.co/mcp \
  -H 'Authorization: Bearer mmak_XXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"mm_create_mailbox","arguments":{"expiresIn":30}}}'

Tool results are returned as MCP text content carrying the gateway's JSON response. Non-2xx gateway responses become isError: true results with the HTTP status and body (401 invalid key, 403 scope/domain, 429 quota with remaining count, 502 upstream down).

Configuration

Development

Go 1.23. Stdlib plus prometheus/client_golang for /metrics. Follows the MinuteMail service standards (see mm-mailbox-service).

go test ./...     # unit tests
go vet ./...
go run .          # local server on :8080