Connect your AI tools

MailGate runs a Model Context Protocol (MCP) server, so compatible AI assistants can read, search, summarize, reply to, and compose mail for your signed-in mailbox. Point your client at one URL and authorize it with OAuth 2.0 + PKCE.

The connection details

Everything below points at that one URL.

Add it to your tool

Claude Code

claude mcp add --transport http mailgate https://api-staging.mailgate.sh/mcp

Add --scope user to make it available in every project. The first time Claude uses it, a browser tab opens to sign in.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (one project):

{
"mcpServers": {
  "mailgate": {
    "url": "https://api-staging.mailgate.sh/mcp"
  }
}
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
"servers": {
  "mailgate": {
    "type": "http",
    "url": "https://api-staging.mailgate.sh/mcp"
  }
}
}

Claude Desktop

Claude Desktop connects to local (stdio) servers, so bridge the remote URL with mcp-remote. Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
"mcpServers": {
  "mailgate": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://api-staging.mailgate.sh/mcp"]
  }
}
}

Restart Claude Desktop after saving. On newer paid plans you can instead add it under Settings → Connectors → Add custom connector.

Codex CLI

Add to ~/.codex/config.toml, again via the mcp-remote bridge:

[mcp_servers.mailgate]
command = "npx"
args = ["-y", "mcp-remote", "https://api-staging.mailgate.sh/mcp"]

Any other MCP client

If your tool only supports local/stdio servers, point it at the same bridge command:

npx -y mcp-remote https://api-staging.mailgate.sh/mcp

Authorize your client

The server advertises OAuth protected-resource metadata when a client reaches /mcp without a bearer token. Complete the browser flow as follows:

1. Sign in to MailGate in the same browser the client uses for OAuth.
2. Review the consent page. It shows the registered client ID and asks you to allow MCP access.
3. Approve the request. MailGate redirects the client with a short-lived authorization code. The client exchanges it using its PKCE verifier and stores the resulting bearer token.

The MCP server validates the bearer token on every request against the live OAuth grant — a revoked or expired token is rejected immediately, not just at its next refresh. Current clients should request the scopes they need from the protected-resource metadata: mcp:read (list/search/read), mcp:send (compose and reply), mcp:write (mark, move, archive, delete, star, and draft), and mcp:gating (manage the inbound allow/block list and toll amount). A token only grants what it asked for and was approved for — the consent page shows the requested scopes in plain language before you approve.

Available tools

MailGate advertises 32 tools, grouped by the scope that gates them:

• mcp:read — whoami, list_agents, check_sender, get_mailbox_summary, list_emails, read_email, search_emails, list_threads, get_thread, list_attachments, get_attachment, counterparty_labels, list_drafts
• mcp:send — send_reply, compose_email, quote_recipients, forward_email, send_draft
• mcp:write — mark_read, mark_unread, move_email, archive_email, delete_email, star_email, create_draft, update_draft
• mcp:gating — add_whitelist_entry, remove_whitelist_entry, add_blacklist_entry, remove_blacklist_entry, get_gating_settings, set_toll_amount

tools/list only returns what your token's scopes, any delegate permissions, and mailbox custody actually allow, so a given session usually sees a subset of the full catalog.

list_agents reports live on-chain delegates; it does not switch the connection into an agent identity. Mail-content tools require an active custodial mailbox because the enclave must decrypt recipient-scoped data safely.

Revoking access

Go to Settings → Connected apps to see every client that has ever authorized against your mailbox, with its granted scopes and last-used time. Click Disconnect to revoke a client's access, tokens, and sessions immediately — the client's next request to /mcp gets a 401 with no grace period.

Good to know

• Sign-in is per client. Each OAuth client has its own authorization-code and refresh-token lifecycle.
• Only implemented tools are advertised. Toll payment/balance, skills, and some agent-policy surfaces are still being built out — see Agents & automation for what's shipped versus planned.
• The full inventory is generated from Rust. A client sees only the subset allowed by its approved scopes, live delegate permissions, and mailbox custody; a smaller tools/list result is not automatically a server regression.
• It's experimental. Like the rest of the agent system, expect the occasional rough edge.

Related