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

# MCP server

> Connect Claude, Cursor, or any MCP client to OpenMail. One hosted URL gives your agent an inbox so it can read, send, and reply to email.

Add one URL to your client. Your agent can then create an inbox, read threads, and reply. OAuth or API key; nothing to install.

## Connect

<Tabs>
  <Tab title="Claude (OAuth)">
    <Steps>
      <Step title="Open Connectors">
        Go to **Settings → Connectors**, click **Add**, then **Add custom connector**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-connectors.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=2932097cb3bad397788ab182d6c84e90" alt="Claude Connectors settings with the Add menu open and Add custom connector highlighted" width="1375" height="912" data-path="images/mcp/claude-connectors.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-connectors-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=8ee385cab397a6ee8d700a78408880cc" alt="Claude Connectors settings with the Add menu open and Add custom connector highlighted" width="1371" height="914" data-path="images/mcp/claude-connectors-dark.png" />
        </Frame>
      </Step>

      <Step title="Name the server">
        | Field | Value |
        | - | - |
        | Name | OpenMail |
        | MCP server URL | `https://mcp.openmail.sh/mcp` |

        Click **Continue**. Claude checks the URL and detects the sign-in settings.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-add-connector.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=afc0e10831bd31e8329d60f9d142497b" alt="Add custom connector dialog with the MCP server URL field highlighted" width="1295" height="1123" data-path="images/mcp/claude-add-connector.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-add-connector-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=91f4302bb7fa529ad171760ceaef1df9" alt="Add custom connector dialog with the MCP server URL field highlighted" width="1295" height="1123" data-path="images/mcp/claude-add-connector-dark.png" />
        </Frame>
      </Step>

      <Step title="Keep the detected auth settings">
        | Field | Value |
        | - | - |
        | Authentication | **Sign in now** |
        | OAuth client | **Use Claude's published identity** (or **Register automatically**) |
        | Request headers | none |

        Both are pre-selected and marked **Detected**. Leave **Advanced** alone and click **Add**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-auth.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=411431a72c9f5fee59bf728be6a10a4d" alt="Add custom connector step 2 with Sign in now and Use Claude's published identity highlighted" width="1295" height="2361" data-path="images/mcp/claude-auth.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/claude-auth-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=f6a18804012f6da0ea3f71a7d2dfe00f" alt="Add custom connector step 2 with Sign in now and Use Claude's published identity highlighted" width="1295" height="2325" data-path="images/mcp/claude-auth-dark.png" />
        </Frame>
      </Step>

      <Step title="Sign in and approve">
        The console opens and shows the client name and host. Pick an organisation if you belong to several. **Read** is always granted; untick **Send**, **Setup**, or **Domains** to withhold them. Revoke any time from [MCP settings](https://console.openmail.sh/settings/mcp).
      </Step>

      <Step title="Confirm">
        Ask *"Which OpenMail inbox can you see?"*. Claude calls `auth_me` and answers with the organisation and inbox.
      </Step>
    </Steps>

    <Note>Custom connectors need a Claude Pro, Max, Team, or Enterprise plan.</Note>
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    claude mcp add --transport http openmail https://mcp.openmail.sh/mcp
    ```

    Claude Code signs in with OAuth on first use. Connectors added on claude.ai do not carry over, so add it here too. Confirm with *"Which OpenMail inbox can you see?"*.

    Prefer the CLI and skill? See [Claude Code](/integrations/claude-code).
  </Tab>

  <Tab title="ChatGPT (OAuth)">
    <Steps>
      <Step title="Turn on Developer mode">
        Go to **Settings → Security and login** and switch on **Developer mode**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-developer-mode.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=19c12e7fd6c13184cf95ffe63326db55" alt="ChatGPT advanced settings with the Developer mode toggle highlighted" width="1583" height="1423" data-path="images/mcp/chatgpt-developer-mode.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-developer-mode-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=dfed4909d1b213872068c69bf38f05a8" alt="ChatGPT advanced settings with the Developer mode toggle highlighted" width="1584" height="1424" data-path="images/mcp/chatgpt-developer-mode-dark.png" />
        </Frame>
      </Step>

      <Step title="Create an app">
        Open **Plugins**, click **+** in the top right, then **Create app**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-create-app.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=6939d4ee253f6c8522e1f33a84f99883" alt="ChatGPT Plugins page with the plus menu open and Create app highlighted" width="1303" height="624" data-path="images/mcp/chatgpt-create-app.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-create-app-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=2079fbc222a676cd379ec26974511dba" alt="ChatGPT Plugins page with the plus menu open and Create app highlighted" width="1512" height="648" data-path="images/mcp/chatgpt-create-app-dark.png" />
        </Frame>

        In the dialog, click **Create MCP App**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-create-mcp-app.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=0f6963d8471e23c250e7a3cddb8fe33e" alt="New Plugin dialog with the Create MCP App button highlighted" width="1247" height="911" data-path="images/mcp/chatgpt-create-mcp-app.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-create-mcp-app-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=25daa04ce154c55686f42b4cfb6a01fa" alt="New Plugin dialog with the Create MCP App button highlighted" width="1248" height="912" data-path="images/mcp/chatgpt-create-mcp-app-dark.png" />
        </Frame>
      </Step>

      <Step title="Fill in the form">
        | Field | Value |
        | - | - |
        | Name | OpenMail |
        | Connection | **Server URL** → `https://mcp.openmail.sh/mcp` |
        | Authentication | **OAuth** |

        Leave **Advanced OAuth settings** alone; ChatGPT identifies itself, and the consent page shows `chatgpt.com` as the host. Tick the risk acknowledgement and click **Create**.

        <Frame>
          <img className="block dark:hidden" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-form.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=23729a58f2ada6b7424a7b94bc9d3461" alt="New Plugin form with the server URL and OAuth authentication fields highlighted" width="1119" height="1837" data-path="images/mcp/chatgpt-form.png" />

          <img className="hidden dark:block" src="https://mintcdn.com/openmail/shproCGer-XtDsSk/images/mcp/chatgpt-form-dark.png?fit=max&auto=format&n=shproCGer-XtDsSk&q=85&s=b61f4268363a2fb192534794eee0221a" alt="New Plugin form with the server URL and OAuth authentication fields highlighted" width="1120" height="1838" data-path="images/mcp/chatgpt-form-dark.png" />
        </Frame>
      </Step>

      <Step title="Sign in and approve">
        The console opens. Sign in, choose an organisation, and untick any scopes the agent should not have.
      </Step>

      <Step title="Confirm">
        In a chat, open the **+** menu, choose **Developer mode**, and select **OpenMail**. Ask *"Which OpenMail inbox can you see?"*. ChatGPT asks before any write action, such as sending mail.
      </Step>
    </Steps>

    <Note>Developer mode is available on Plus, Pro, Business, Enterprise, and Edu plans.</Note>
  </Tab>

  <Tab title="Cursor">
    Install the [OpenMail plugin](https://cursor.directory/plugins/openmail) from cursor.directory, or click once here and sign in when Cursor prompts you:

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=openmail&config=eyJ1cmwiOiJodHRwczovL21jcC5vcGVubWFpbC5zaC9tY3AifQ==">
      <img noZoom className="block dark:hidden" src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Add OpenMail MCP server to Cursor" height="32" />

      <img noZoom className="hidden dark:block" src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add OpenMail MCP server to Cursor" height="32" />

      <span className="sr-only">Add OpenMail MCP server to Cursor</span>
    </a>

    Or edit `.cursor/mcp.json` by hand. Drop `headers` for OAuth; keep it for a headless agent:

    ```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    {
      "mcpServers": {
        "openmail": {
          "url": "https://mcp.openmail.sh/mcp",
          "headers": { "Authorization": "Bearer om_YOUR_KEY" }
        }
      }
    }
    ```

    <Tip>Use an inbox-scoped key, from the console or `openmail inbox keys create`. Keys go in the header, never the URL.</Tip>

    Confirm with *"Which OpenMail inbox can you see?"* in a Cursor chat.
  </Tab>

  <Tab title="VS Code / registry">
    OpenMail is in the [MCP Registry](https://registry.modelcontextprotocol.io) as `sh.openmail/openmail`. In VS Code, run **MCP: Add Server**, search for **OpenMail**, and sign in when prompted. Any registry-aware client installs it the same way.
  </Tab>

  <Tab title="stdio-only clients">
    Bridge with `mcp-remote`:

    ```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    {
      "mcpServers": {
        "openmail": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.openmail.sh/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Info>Without a credential, `/mcp` answers `401` and your client starts sign-in. An agent that only needs these docs can use `https://mcp.openmail.sh/mcp/public`: no sign-in, just `search_docs` and `get_docs`.</Info>

## First run

Ask your agent: *"Set up an inbox for this agent and show me the address."*

It calls `setup_agent_email`, which shows a plan first. Confirm, and it creates the inbox. Over OAuth no key is minted; the session already has access, and the tool points to the console if another agent needs one. Over an API key, a new inbox-scoped key appears once in the result.

<Warning>Move that key to the agent's environment now. If the transcript is shared, revoke it in the console.</Warning>

## Tools

<Note>19 tools. Your client reads the live list from the server; this table can lag a release.</Note>

| Tool | What it does |
| - | - |
| `search_docs`, `get_docs` | Search and read these docs. Also available without sign-in at `/mcp/public`. |
| `auth_me` | Which organisation and inbox this credential can see. |
| `setup_agent_email` | Plan, then create an inbox and mint a scoped key. |
| `list_inboxes`, `get_inbox`, `create_inbox`, `mint_inbox_key` | Inbox management. |
| `list_unread_threads` | Unread threads whose latest message is `autoReplyable`: sent by a person or another agent. Spam, marketing, bounces, and machine-generated mail (no-reply, OTPs, receipts) are filtered out. |
| `read_thread` | Full thread as Markdown with timestamps, `autoReplyable` flags, and attachment message ids. Quoted reply history is stripped. |
| `reply_to_thread`, `send_email` | Reply in-thread, or start a new one. `send_email` names the inbox it used when you did not pass `inbox_id`. |
| `mark_thread_read` | Mark a thread handled. |
| `get_attachment_text` | Extracted text from an attachment. Use the `message:` id shown in `read_thread`. |
| `list_domains`, `add_domain`, `get_domain`, `verify_domain` | Custom domains with pasteable DNS records. Pro plan. |
| `send_mcp_feedback` | Report a confusing or broken tool to the OpenMail team. |

Tools follow the credential. An inbox-scoped key hides `list_inboxes`, `setup_agent_email`, and the domain tools.

## Narrow what the agent can do

| Goal | URL |
| - | - |
| Read only, no sending | `https://mcp.openmail.sh/mcp/readonly` or `?readonly=true` |
| One inbox, no discovery | `https://mcp.openmail.sh/mcp/inbox/INBOX_ID` |
| Fewer tools | `?toolsets=mailbox,docs` or the `X-MCP-Toolsets` header |

## What the connected client can do

A connected client sees whatever the tools return: thread contents, attachment text, inbox addresses. With **Send** it can also send and reply as your inbox. That data falls under the client's own terms, so connect only clients you trust and untick scopes the agent does not need. Revoking the connection in [MCP settings](https://console.openmail.sh/settings/mcp), or its API key, stops access at once.

## Usage analytics

The server records how tools are used so the OpenMail team can fix the ones that fail or confuse agents. Each tool accepts an optional `context` argument: one line from the agent on what it is trying to do. That line is recorded too.

| Recorded | Never recorded |
| - | - |
| Tool name, success or failure, latency | Message bodies, subjects, recipients |
| Client name and version (Claude, Cursor, ChatGPT) | Attachment text |
| The agent's `context` line | Inbox names and display names |
| Your organisation id | API keys and OAuth tokens |

Tool results never leave the server, except from `search_docs` and `get_docs`, which return public documentation.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The consent page asks for an account you do not have">
    Sign up at [console.openmail.sh](https://console.openmail.sh/signup), then connect again from your client.
  </Accordion>

  <Accordion title="You picked the wrong organisation">
    Revoke it in [MCP settings](https://console.openmail.sh/settings/mcp) and connect again. The consent page shows the picker each time.
  </Accordion>

  <Accordion title="401 with an API key">
    Check the key starts with `om_`, is complete, and is not revoked. It belongs in the `Authorization: Bearer` header, not the URL. A leftover `om_YOUR_KEY` placeholder in Cursor gives the same error.
  </Accordion>

  <Accordion title="Tools are missing">
    An inbox-scoped key hides `list_inboxes`, `setup_agent_email`, and the domain tools on purpose. After changing scopes, disconnect and reconnect so the client reloads the list.
  </Accordion>

  <Accordion title="Claude says it cannot reach OpenMail">
    Check **Settings → Connectors** shows OpenMail as connected. If not, repeat the Claude steps.
  </Accordion>
</AccordionGroup>

## Example prompts

* Set up an inbox for this agent and show me the address.
* Reply to my unread mail.
* Read the invoice attached to the latest thread and summarise it.
* Add and verify `mail.example.com`.

## Related

* [Claude Code](/integrations/claude-code): CLI and skill instead of MCP
* [Agent keys](/best-practices/api-key-scopes): why inbox-scoped keys
* Source: [openmailsh/mcp](https://github.com/openmailsh/mcp) (MIT)


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