MCP Server Setup

Saymail ships a built-in Model Context Protocol (MCP) server. Create one API key and any MCP-aware assistant — Claude Code, Claude Desktop, Cursor, VS Code, Codex, Raycast, and others — can read, search, draft, send, and sync your email, without you copying anything by hand.

What is the Model Context Protocol?

MCP is an open protocol that standardises how applications expose context and actions to large language models. Think of it as a USB-C port for AI: instead of a bespoke integration per tool, an assistant speaks one protocol and plugs into anything that implements it. Learn more at modelcontextprotocol.io.

Saymail’s MCP server runs on your device. It listens only on http://127.0.0.1:17057/mcp and is never reachable from outside your machine. Saymail must be running, and the server only starts once you have at least one active API key — it stops again when the last active key is removed or deactivated.

Quick start

Step 1 — Create an API key

1. Open the MCP API Keys panel (via the command palette or menu).
2. Click New and give the key a recognisable name, such as Claude Code.
3. Choose the permissions to grant (see Permissions below).
4. Optionally link the key to specific email accounts. Leave this empty to allow all accounts.
5. Make sure Active is checked, then click Save.
6. Copy the generated key — it starts with smk_ and is shown only once. Store it somewhere safe. The panel also offers a Copy URL button with the token baked in, handy for clients that take a plain URL.

Step 2 — Connect your AI assistant

Pick your client. Every snippet registers a server named saymail pointing at http://127.0.0.1:17057/mcp — replace smk_… with the key you copied.

claude mcp add --transport http saymail http://127.0.0.1:17057/mcp \
  --header "Authorization: Bearer smk_…"

claude mcp list

{
  "mcpServers": {
    "saymail": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:17057/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer smk_…"
      }
    }
  }
}

{
  "mcpServers": {
    "saymail": {
      "url": "http://127.0.0.1:17057/mcp",
      "headers": {
        "Authorization": "Bearer smk_…"
      }
    }
  }
}

{
  "servers": {
    "saymail": {
      "type": "http",
      "url": "http://127.0.0.1:17057/mcp",
      "headers": {
        "Authorization": "Bearer smk_…"
      }
    }
  }
}

[mcp_servers.saymail]
url = "http://127.0.0.1:17057/mcp"
http_headers = { "Authorization" = "Bearer smk_…" }

[mcp_servers.saymail]
url = "http://127.0.0.1:17057/mcp"
bearer_token_env_var = "SAYMAIL_TOKEN"

Connection details

For any client not listed above, these are the raw connection facts:

Prefer the header. The ?token= query-string form exists for clients that can’t set custom headers, and is safe only because the server listens on loopback. The Copy URL button in the MCP API Keys panel produces exactly this token URL.

The stdio bridge (mcp-remote)

Some clients can only launch stdio servers, or can’t attach a static header (Claude Desktop is the notable case). For those, mcp-remote bridges a stdio client to the HTTP server. It needs Node.js 18+.

Install Node.js

node -v

node -v

node -v

Run the bridge

The wrapped command, used inside a stdio client’s config (see the Claude Desktop tab above):

npx mcp-remote http://127.0.0.1:17057/mcp --allow-http --header "Authorization: Bearer smk_…"

--allow-http is required because the endpoint is plain http:// on loopback rather than HTTPS.

Permissions

Each API key grants exactly the permissions you check. Tools that need a permission the key lacks return permission denied.

Granting Write without Send is useful for an agent-drafts / human-sends workflow: the assistant prepares messages, you press send.

Tools

The server exposes these tools, each gated by the permission shown:

Account scoping

When a key is linked to specific accounts, assistants can only read or send mail for those accounts — even if the key has Write or Send. An empty account list grants access to every account configured in Saymail. Create multiple keys to give different tools different reach.

Resetting a key

If a key is exposed, open the MCP API Keys panel, select the key, and click Reset Key. A new key is generated immediately and the old one stops working at once. Update the registration in your assistant with the new token.

Stopping the server

To turn the MCP server off, deactivate every key (uncheck Active) or delete them. Once no active keys remain, Saymail closes port 17057 automatically.

Troubleshooting

• Connection refused / can’t reach the server. Saymail must be running and you need at least one active API key — the server only listens while a key is active.
• 401 Unauthorized. The token is wrong, was reset, or its key is inactive. Copy the current key (or reset it) and update your client.
• Codex says missing field 'command'. Your Codex predates streamable-HTTP support. Upgrade Codex, or opt in by adding experimental_use_rmcp_client = true under a [features] table in ~/.codex/config.toml.
• mcp-remote fails on Windows with a mangled header. Move the header value into an env variable and reference it as Authorization:${AUTH_HEADER} with no space after the colon, as shown in the Claude Desktop tab.
• mcp-remote refuses to connect. Pass --allow-http; the loopback endpoint is plain HTTP, which the bridge otherwise rejects.