# Connect mailconnect to your MCP client mailconnect is a hosted Fastmail MCP server. It speaks remote streamable HTTP with OAuth 2.0 (PKCE + Dynamic Client Registration). MCP clients that support that shape can connect without any manual app paperwork. ## Endpoint - **MCP URL:** `https://api.mailconnect.app/mcp` - **Transport:** streamable HTTP - **Auth:** OAuth 2.0 with PKCE - **OAuth metadata:** `https://api.mailconnect.app/.well-known/oauth-authorization-server` - **Client registration:** RFC 7591 Dynamic Client Registration at `/register` On first tool call, your client will open a browser to the mailconnect consent screen, then bounce you to Fastmail to sign in. Your Fastmail password never touches mailconnect. ## Compatibility | Client | Status | Notes | |---|---|---| | Poke | Works | One-tap recipe, zero config | | Claude.ai (Pro / Max) | Works | Added via Connectors UI | | Claude Desktop / Team / Enterprise | Works | Added via Connectors UI; orgs need an owner to enable it | | Claude Code | Works | `claude mcp add` CLI | | Cursor | Works | Edit `.cursor/mcp.json` | | ChatGPT (Plus/Pro/Business/Enterprise) | Works, gated | Requires workspace developer mode | | ChatGPT (Free) | Not supported | Custom MCP connectors aren’t available on Free | | Local-only / stdio MCP clients | Not supported | mailconnect is remote HTTP only | If your client expects a local command to stdio (e.g. older Claude Desktop config, older MCP Inspector setups), it will not work directly. You need a client that understands the remote streamable HTTP transport. ## Poke Install the published Poke recipe: https://poke.com/refer/yJdl5KDDc8c After install, sign in to Fastmail on the consent screen. Done. ## Any coding agent (one prompt) Paste the prompt below into Claude Code, Codex, Cursor agent mode, or any other coding agent. The agent picks the right flow for its environment: if it has a native MCP-config surface it uses that (and the normal browser OAuth runs on first tool call); if it doesn't, it runs the RFC 8628 device authorization grant and walks you through the `user_code` step. ``` Connect me to mailconnect, a hosted MCP server for my Fastmail account. Server URL: https://api.mailconnect.app/mcp (streamable HTTP, OAuth 2.0 + PKCE, RFC 7591 Dynamic Client Registration, RFC 8628 device authorization grant) Do whichever of these applies to you, in order: 1. If you have a native MCP-config command or file on this machine (e.g. `claude mcp add`, editing `.cursor/mcp.json`, writing `.mcp.json`), use it with the URL above and transport `http`, then trigger a tool call so the browser OAuth flow runs. Stop here on success. 2. Otherwise, run the device flow yourself: a. POST https://api.mailconnect.app/register with JSON body {"client_name":"", "redirect_uris":["http://127.0.0.1/callback"], "grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"], "token_endpoint_auth_method":"none"} Keep the returned client_id. b. POST https://api.mailconnect.app/device_authorization as application/x-www-form-urlencoded with body client_id=&scope=mailconnect You get {device_code, user_code, verification_uri, interval, expires_in}. c. Show me user_code and verification_uri and wait. I'll open the URL, enter the code, sign in to Fastmail, and approve. d. Poll https://api.mailconnect.app/token every `interval` seconds with form-urlencoded body grant_type=urn:ietf:params:oauth:grant-type:device_code &client_id=&device_code= On authorization_pending keep polling. On slow_down increase the interval. On access_denied or expired_token, stop and tell me. On success, save access_token and refresh_token. e. Use access_token as `Authorization: Bearer ` on every request to /mcp. Don't invent an MCP-config command you don't actually have. If unsure, use option 2. ``` ## Claude (claude.ai, Claude Desktop, Team, Enterprise) As of April 2026, Claude uses **Connectors** for remote MCP servers. This is a different surface from `claude_desktop_config.json` (which only handles **local** stdio MCP servers). Don’t edit that file for mailconnect — it won’t work. **On claude.ai (Pro / Max):** 1. Open **Settings → Connectors**. 2. Click **Add custom connector**. 3. Enter the MCP URL: `https://api.mailconnect.app/mcp`. 4. Save. Claude will run the OAuth flow on first use. **On Team or Enterprise:** A workspace owner must add it first via **Organization settings → Connectors → Add → Custom**. Members then **Connect** to it from their own Connectors list. Each member authorizes their own Fastmail account; nobody shares tokens. **Note:** Claude connects from Anthropic’s cloud infrastructure, not your local machine. mailconnect is publicly reachable, so that’s fine. ## Claude Code From a shell: ```sh claude mcp add mailconnect https://api.mailconnect.app/mcp --transport http ``` Default scope is `local` (only this project, this machine). For repo-committed config, use `--scope project` (writes to `.mcp.json` at the repo root) or `--scope user` (available across all your projects). You can also commit `.mcp.json` by hand: ```json { "mcpServers": { "mailconnect": { "type": "http", "url": "https://api.mailconnect.app/mcp" } } } ``` On the next `claude` invocation that uses a mailconnect tool, Claude Code will open the OAuth flow in a browser. ## Cursor Cursor reads MCP config from either: - `.cursor/mcp.json` in the workspace root (project-scoped), or - `~/.cursor/mcp.json` in your home directory (global, across all workspaces). Add: ```json { "mcpServers": { "mailconnect": { "url": "https://api.mailconnect.app/mcp" } } } ``` Cursor will handle the OAuth flow via its own redirect URL (`cursor://anysphere.cursor-mcp/oauth/callback`) on first tool call. You don’t need to pre-configure a client id or secret — mailconnect supports Dynamic Client Registration, and Cursor will register itself. ## ChatGPT (Plus, Pro, Business, Enterprise) Custom MCP connectors are a **beta** feature and require **developer mode**. 1. A workspace admin enables developer mode: **Workspace Settings → Permissions & Roles → Connected Data → Developer mode / Create custom MCP connectors**. 2. Any member then goes to **Settings → Apps & Connectors → Add new connector**. 3. Enter `https://api.mailconnect.app/mcp` as the MCP server URL. 4. Set authentication to **OAuth**. 5. Confirm **I trust this application**, then **Create**. 6. Complete the OAuth login for your Fastmail account. ChatGPT Free does not currently support custom MCP connectors. ## Custom / other MCP clients Any client that implements the MCP remote streamable HTTP transport plus OAuth 2.0 Authorization Code with PKCE and Dynamic Client Registration will work. The handshake: 1. Fetch `/.well-known/oauth-authorization-server` for OAuth endpoint metadata. 2. POST to `/register` (RFC 7591) to get a `client_id`. 3. Run an authorization code flow against `/authorize` with PKCE (S256). 4. Exchange the code at `/token` for an MCP access token. 5. Use the token as a bearer on every request to `/mcp`. Local-only or stdio-only MCP clients are not supported — mailconnect has no stdio entry point. ## What the server exposes **Read-only tools, always available:** - `get_account_profile` — connected Fastmail identity, granted scopes, JMAP capabilities - `list_mailboxes` — Inbox, Archive, Sent, and custom mailboxes with roles and unread counts - `search_emails` — by text, sender, recipient, subject, mailbox, unread, attachment, date window - `get_email` — full message with headers, recipients, attachments, and plain-text body - `download_attachment` — fetch an attachment by blob id **Write tools, disabled by default, opt-in per connected client:** - `move_email` — move a message between mailboxes - `mark_email_read` — mark a message read or unread You enable write access for a specific client in mailconnect settings. Other connected clients stay read-only unless you enable them individually. A client may need one reconnect after you enable new tools before they appear in its tool list. ## Disconnect From inside your MCP client, remove the mailconnect connection. To also revoke the upstream Fastmail authorization, visit **Fastmail settings → Password & Security → Connected apps** and revoke mailconnect from there. ## Support - Support: https://mailconnect.app/support - Email: support@mailconnect.app - Privacy: https://mailconnect.app/privacy - Terms: https://mailconnect.app/terms