MCP Server Setup

What is Saymail’s MCP server?

Saymail includes a built-in Model Context Protocol (MCP) server that lets AI assistants such as Claude Code, Claude Desktop, and Cursor access your email. They can read messages, search, send, and trigger syncs — without you copying anything manually.

The server runs locally on http://127.0.0.1:17057/mcp and is not reachable from outside your machine. Access is controlled through API keys: each key defines what an AI assistant is allowed to do and which email accounts it can reach. The server starts automatically as soon as you have at least one active API key, and stops again when the last active key is deleted or deactivated.

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 recognizable name, such as Claude Code.
3. Set the permissions you want to grant the AI assistant (see table below).
4. Optionally link the key to specific email accounts. Leave this empty to grant access to all accounts.
5. Make sure Active is checked. Click Save.
6. Copy the generated key — it starts with smk_ and is shown only once. Store it somewhere safe.

Permissions

Permission	What it allows
Account Info	List configured email accounts (list_email_accounts)
Read	List inbox, search emails, read message details, view contacts, get unread counts, list tasks
Write	Mark as read, delete, flag, mark as spam, send emails (attachments not supported yet)
Sync Control	Trigger a manual sync, cancel running tasks

Step 2 — Register with Claude Code

Run the following command in your terminal. Replace smk_… with your actual API key.

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

Then verify the server is recognised:

claude mcp list

Or type /mcp inside a Claude Code session to check the connection status.

Account scoping

When you link a key to specific accounts, AI assistants can only read or send email for those accounts — even if the key has write permission. An empty account list grants access to all accounts configured in Saymail.

Create multiple keys to give different AI tools different levels of access.

Resetting a key

If a key is compromised, open the MCP API Keys panel, select the key, and click Reset Key. A new key is generated immediately; the old one stops working right away. Update the registration in Claude Code with the new token.

Stopping the server

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