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://dev.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://dev.mailgate.sh/mcp"
  }
}
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
"servers": {
  "mailgate": {
    "type": "http",
    "url": "https://dev.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://dev.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://dev.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://dev.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. Current clients should request the web scope advertised by the protected-resource metadata.

Available tools

The currently wired tool set is deliberately small:

• whoami, list_agents, check_sender, and get_mailbox_summary
• list_emails, read_email, and search_emails
• send_reply and compose_email

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.

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. Mail forwarding, mutable gating controls, payments, skills, and agent-JWT policy enforcement are not exposed through MCP yet.
• It's experimental. Like the rest of the agent system, expect the occasional rough edge.

Related