How to Configure the MCP Server

mailserver-admin can offer an MCP endpoint, so that an agent can manage domains, users, aliases, fetchmail accounts and DKIM, run DNS validation, and read, draft and send mail in the mailbox of the token's owner. It is on by default, and only acts for API tokens that users create themselves.

Read MCP server: risks and limitations first. Mail can put instructions in front of an agent that reads it, passwords given to a tool pass through the agent, and a failing call can write its arguments to the error log.

Prerequisites

Steps

1. Set the allowed hostnames

In .env:

MCP_ALLOWED_HOSTS=mail.example.com

MCP_ALLOWED_HOSTS is the comma-separated list of hostnames clients use to reach the server, without a port. Requests for any other hostname get 403 Forbidden: Invalid Host header.

MCP_ENABLED=false turns the endpoint and the API token pages off. MCP_MAIL_READ_ENABLED=false and MCP_MAIL_SEND_ENABLED=false switch off only the mail tools. The two are independent. message_send also logs in over IMAP to keep a copy in the Sent mailbox, and message_draft logs in to save the draft in the Drafts mailbox, whether or not reading is enabled. message_draft has no flag of its own: leave out the scope mail:draft to prevent drafting.

2. Apply the configuration

Docker Compose:

bin/production.sh up -d web

Kubernetes, when you apply the root kustomization.yaml:

bin/kubernetes-env.sh
kubectl apply -k .
kubectl rollout restart deployment/web

An overlay with its own ConfigMap sets the variable in config-env.

3. Preserve the Host header

The endpoint matches the raw Host header, so a reverse proxy must pass it on unchanged. See Preserve the Host header.

4. Create a token

  1. Log in to the management interface. This works with a local password and with OAuth2.
  2. Open API tokens in the menu, under Security.
  3. Click Create API token.
  4. Enter a name, choose the scopes and set the validity in days. Only manage:read and mail:read are preselected. Tick manage:write, mail:draft and mail:send if the agent needs them, and remove the scopes it does not need:
  • Give an agent that reads mail no other scope.
  • Use separate tokens, and separate agents, for reading, sending and managing.
  • For an agent that drafts mail, use mail:read and mail:draft and have the person send the drafts.
  • Do not use an admin's token for an agent that reads mail.
  1. If you ticked mail:send or mail:draft, choose the sender: Primary address only, A fixed address and the address, or Any of my addresses. Bind an agent to one address unless it has to choose. The sender cannot be changed later.
  2. Copy the token, which starts with msa_. It is only shown once.

Use one token per agent, so that you can revoke them separately.

5. Configure the client

The endpoint is https://<hostname>/mcp. It uses the MCP Streamable HTTP transport and expects the token as Authorization: Bearer <token>. Any client that can send this header can connect. Clients that only support the OAuth flow cannot.

The MCP page in the menu of the management interface shows the address and the configuration for common clients. For example, Claude Code reads this from .mcp.json:

{
  "mcpServers": {
    "mailserver": {
      "type": "http",
      "url": "https://mail.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MAILSERVER_MCP_TOKEN}"
      }
    }
  }
}

Keep the token in the environment variable, not in a file you commit. If the client can ask for approval before a tool runs, require it for message_send and for the tools that write. If one client holds both mail:read and mail:send, have a person approve every send.

6. Protect what passes through

  1. Restrict who can read the logs of the web container (docker logs, kubectl logs, log collectors) and how long they are kept.
  2. Set passwords in the web interface wherever the agent's context and its history must not hold them, or change them there afterwards.

Verification

Without a token, the endpoint answers 401 with WWW-Authenticate: Bearer. A 404 means MCP_ENABLED is false:

curl -i -X POST https://mail.example.com/mcp

With a token, this answers 200 with an Mcp-Session-Id header. A 403 means the hostname is not in MCP_ALLOWED_HOSTS, or a proxy changed the Host header:

curl -i https://mail.example.com/mcp \
  -H "Authorization: Bearer ${MAILSERVER_MCP_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

In the client, call the whoami tool. It returns the user, role, domain and the scopes of the token, and for a token that sends or drafts mail, its sender in send_as.

For every tool, scope and limit, see MCP server reference. For variables, see Environment variables reference.