> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getinboxzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect ChatGPT, Claude, Cursor, or another assistant to Inbox Zero mail, drafts, rules, and statistics with OAuth.

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:

```bash theme={null}
NEXT_PUBLIC_EXTERNAL_API_ENABLED=true
MCP_SERVER_ENABLED=true
API_KEY_SALT=<random salt>
```

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:

```text theme={null}
https://www.getinboxzero.com/mcp
```

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.

<Accordion title="ChatGPT">
  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.
</Accordion>

<Accordion title="Claude">
  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.

  ```bash theme={null}
  claude mcp add --transport http inbox-zero https://www.getinboxzero.com/mcp
  ```

  Claude Code then runs OAuth against that URL.
</Accordion>

<Accordion title="Cursor">
  Add this to `~/.cursor/mcp.json` or `.cursor/mcp.json`:

  ```json theme={null}
  {
    "mcpServers": {
      "inbox-zero": {
        "url": "https://www.getinboxzero.com/mcp"
      }
    }
  }
  ```

  Cursor then runs OAuth. Self-hosted deployments use their own origin in place of `www.getinboxzero.com`.
</Accordion>

See [Connect MCP](/essentials/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:

| Scope | Access |
| - | - |
| `mcp:read` | List inboxes, search and read email, read automation rules, and read email statistics |
| `mcp:write` | Create mailbox drafts and create, replace, or delete automation rules. Does not send email. |
| `mcp:send` | Send email. Granted only when a client requests it. |
| `offline_access` | Obtain rotating refresh tokens |

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](https://github.com/elie222/inbox-zero/blob/main/docs/better-auth-1.7-upgrade.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.