Skip to main content
The optional MCP server lets ChatGPT, Claude, Cursor, or another assistant search and read your inbox, create mailbox drafts, manage automation rules, and read email statistics. It uses OAuth instead of API keys. It is separate from the integrations that let Inbox Zero call other services. The standard tools never send mail: drafts stay in the mailbox until you send them yourself. Sending requires the separate mcp:send scope, which you approve per app.

​
Enable the server

For a deployment you administer, apply the database migrations and set:
The server is disabled by default. Configure NEXT_PUBLIC_BASE_URL to your deployment’s canonical public HTTPS origin. Restart the application after changing server configuration; changing the public API flag also requires rebuilding its client assets.

​
Connect an assistant

Add a remote Streamable HTTP MCP connection:
Self-hosted deployments use https://your-inbox-zero-host/mcp. /api/mcp-server still accepts MCP POST requests as an alias; the OAuth resource identifier is always /mcp. The client must support OAuth authorization-code flow with S256 PKCE, dynamic client registration, and resource indicators. Use the MCP endpoint URL as the resource when authorizing, exchanging an authorization code, and refreshing a token. Opaque tokens and API keys are not accepted. Sign in with your connected provider, then choose Allow. Email-code sessions cannot authorize clients or change MCP access. Refresh tokens stay valid after you log out of Inbox Zero in the browser. Disconnect the app or turn off MCP in Settings to revoke them.
In ChatGPT, open Settings → Apps, turn on Developer mode, and create a new app or connector. Paste the MCP URL, scan tools, then sign in to Inbox Zero and choose Allow. Enable the app from the tools menu in a new chat.
In Claude, open Customize → Connectors, choose Add custom connector, and paste the MCP URL. Leave OAuth client ID and secret empty unless you registered a client yourself. Connect, choose Allow, then enable Inbox Zero from + → Connectors in a chat.
Claude Code then runs OAuth against that URL.
Add this to ~/.cursor/mcp.json or .cursor/mcp.json:
Cursor then runs OAuth. Self-hosted deployments use their own origin in place of www.getinboxzero.com.
See Connect MCP for ChatGPT, Claude, and Cursor steps plus the in-app toggle and per-app disconnect UI. Permissions apply to all inboxes linked to your user, including inboxes linked later: Clients registered without explicit scopes default to read access and refresh tokens. They must request mcp:write to create drafts or manage rules. A write grant does not imply a read grant. Rule writes enforce the same digest-plan restrictions as the public API. On the consent screen you can deselect any requested scope except mcp:read.

​
Available tools

  • list_email_accounts
  • search_inbox, read_thread
  • create_draft (does not send)
  • list_rules, get_rule, create_rule, update_rule, delete_rule
  • get_stats_by_period, get_response_time_stats
Search returns metadata and snippets. Use read_thread for truncated plain-text bodies. Inbox, rule, and statistics tools accept either emailAccountId or emailAddress. If neither is supplied, they use the earliest linked account. Use list_email_accounts and supply a selector when working with multiple inboxes. Rule updates replace the rule definition.

​
Disconnect applications

Open Settings → Account → MCP and choose MCP apps to disconnect one client. That revokes that app’s tokens and consent. Other apps stay connected. You can also remove individual permissions from an app there; adding permissions back requires reconnecting from the app. Turn off MCP to revoke every MCP consent and refresh grant and invalidate existing access tokens. Turning MCP back on does not restore those tokens; reconnect each application to grant access again.

​
Discovery

  • Protected resource metadata: /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp
  • Authorization server metadata: /.well-known/oauth-authorization-server/api/auth
  • Root discovery fallback: /.well-known/oauth-authorization-server
Unauthenticated MCP requests return 401 with a WWW-Authenticate header pointing to the resource metadata. The MCP endpoint is stateless and accepts HTTP POST; it does not offer a persistent event stream. Dynamic client registration, token exchange, and MCP POST requests are rate-limited. Retry after the Retry-After header when you receive 429.

​
Authentication dependency

The server uses Better Auth 1.7.4, which includes the OAuth resource-binding security fix. It permits exactly its MCP endpoint, requires that resource during token issuance, and rejects access tokens with additional audiences. Existing deployments must follow the Better Auth upgrade checklist before applying the authentication migration. MCP accepts HTTPS base URLs, with HTTP allowed only for local loopback development. Turning off the server flag suspends access; users can still revoke previously enabled access from Settings while the external API settings remain available.