MCP for AI agents

Overview

Mailman's MCP server lets an AI agent work with the mail in your Mailman. Every tool is read-only: an agent can search, read and wait for mail, but never send, delete or change it.

1. Create a key

   In Mailman's settings, create a remote key for the agent. It starts with mmr_.

2. Add the server

   Point the agent at https://mcp.getmailman.app/mcp and send the key as a bearer token.

3. Your computer answers

   Mailman's relay forwards each request to Mailman on your computer. Your mail stays there.

Before you start

• Mailman is open on your computer, signed in to your license. When it's closed, agents still see the tools, and every call explains that Mailman isn't reachable.
• Remote access is on in Settings → Remote access & API → Web inbox.
• The agent calls from a server or a local program. Requests from browser pages (with an Origin header) are refused.
• Tool calls can take up to 90 seconds (waits and syncs). Set the agent's tool timeout to about 100 seconds.

Get a remote key

1. In Mailman, open Settings → Remote access & API → Remote agents.
2. Click Create remote key and name it after the agent, for example “Grok bot”.
3. Copy the key now: Mailman shows it only once. Put it in the agent's secret or header settings, not in a chat message.

Connect your agent

Every client needs the same two things: the URL https://mcp.getmailman.app/mcp and the header Authorization: Bearer <remote key>. Use mailman where a name or label is asked for. Mailman takes a remote key with or without the Bearer prefix, so a platform's “authorization” or “token” field works either way.

xAI Grok

Add Mailman as a remote MCP tool in xAI's Responses API, or with the xAI Python SDK:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.7",
  "input": [{"role": "user", "content": "What is the latest verification code in my Mailman inbox?"}],
  "tools": [
    {
      "type": "mcp",
      "server_url": "https://mcp.getmailman.app/mcp",
      "server_label": "mailman",
      "server_description": "Read-only access to the mail in Mailman",
      "authorization": "Bearer '"$MAILMAN_REMOTE_KEY"'"
    }
  ]
}'

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        mcp(
            server_url="https://mcp.getmailman.app/mcp",
            server_label="mailman",
            extra_headers={"Authorization": "Bearer " + os.environ["MAILMAN_REMOTE_KEY"]},
        ),
    ],
)
chat.append(user("What is the latest verification code in my Mailman inbox?"))
print(chat.sample().content)

OpenAI

A remote MCP tool in the Responses API:

{
  "type": "mcp",
  "server_label": "mailman",
  "server_url": "https://mcp.getmailman.app/mcp",
  "headers": { "Authorization": "Bearer <remote key>" },
  "require_approval": "never"
}

Claude

No key needed. In Claude (web, desktop or mobile), open Settings → Connectors → Add custom connector, paste https://mcp.getmailman.app/mcp, sign in with your Mailman account and approve. Pick the computer the connection should use.

Claude Code

claude mcp add --transport http mailman https://mcp.getmailman.app/mcp \
  --header "Authorization: Bearer <remote key>"

Codex

Add to ~/.codex/config.toml, and set MAILMAN_REMOTE_KEY before starting Codex:

[mcp_servers.mailman]
url = "https://mcp.getmailman.app/mcp"
bearer_token_env_var = "MAILMAN_REMOTE_KEY"
tool_timeout_sec = 100

Cursor

Add to .cursor/mcp.json, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "mailman": {
      "url": "https://mcp.getmailman.app/mcp",
      "headers": { "Authorization": "Bearer <remote key>" }
    }
  }
}

Clients that only launch local servers

Bridge with mcp-remote (needs Node.js). The version is pinned on purpose: the bridge receives your key, so a new release should not run until you have looked at it.

{
  "mcpServers": {
    "mailman": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.15.2", "https://mcp.getmailman.app/mcp", "--header", "Authorization:${MAILMAN_AUTH}"],
      "env": { "MAILMAN_AUTH": "Bearer <remote key>" }
    }
  }
}

Any other client, or your own code

Send JSON-RPC over HTTPS. A working connection answers mailman_status with the app version, license and account count:

KEY='<remote key>'
curl -sS https://mcp.getmailman.app/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-bot","version":"1.0"}}}'

curl -sS https://mcp.getmailman.app/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mailman_status","arguments":{}}}'

OAuth sign-in

Platforms with MCP sign-in can connect without a key. A request without one gets 401 and a WWW-Authenticate header that points to the protected-resource metadata. The authorization server is https://api.getmailman.app: OAuth 2.1 with PKCE (S256), dynamic client registration and public clients, scope mailman. You sign in, approve the app and pick a computer. Revoke connected apps in Mailman's settings or on the dashboard.

Tools

Arguments are JSON; ? marks optional ones. Mail content comes back as untrusted data in structuredContent, and failures set isError: true.

Troubleshooting

Set up with AI

Give your agent, or the AI that builds it, the MCP guide. It is one Markdown file with the URL, authentication, setup for each platform, the tools and the error answers.