MCP Server Reference

The MCP endpoint of mailserver-admin. For setup, see How to configure the MCP server. For the risks, see MCP server: risks and limitations.

Endpoint

Property Value
Path /mcp
Transport MCP Streamable HTTP
Authentication Authorization: Bearer <token>
Session storage Redis, so requests can reach any replica of web
Enabled by MCP_ENABLED, on by default
Hostnames MCP_ALLOWED_HOSTS, matched against the Host header

HTTP responses

Status Cause
401 Missing, unknown, expired or revoked token, or a disabled owner. Carries WWW-Authenticate: Bearer
403 With a valid token: the Host header is not in MCP_ALLOWED_HOSTS, or an Origin header names another origin
404 MCP_ENABLED is false, for every HTTP method. The API token pages answer the same way, and their menu entry is hidden

The Host match ignores case and port. X-Forwarded-Host is not considered.

API tokens

Property Value
Format msa_ followed by 64 hexadecimal characters. Only a SHA-256 hash is stored, and the token is shown once
Lifetime 1 day up to MCP_TOKEN_MAX_LIFETIME_DAYS. Mandatory. Lowering the variable does not shorten existing tokens
Owner The user who created it. Nobody can create a token for someone else
Role The owner's role and enabled flag, read from the database on every request
Revoked By hand; automatically when the owner's password changes or the owner is disabled. A revoked token stays revoked if the owner is re-enabled
Listed Users see their own tokens, domain admins those of their domain, admins all. Revoked tokens stay listed until their owner is deleted
Sender Chosen at creation for tokens with mail:send or mail:draft, see Sender. Cannot be changed

Scopes

A call succeeds only if the token carries the scope and the owner's current role allows the action on that object.

Scope Allows Preselected
manage:read List and read domains, users, aliases, fetchmail accounts, DKIM status; DNS validation yes
manage:write Create, update and delete the same no
mail:read Read the owner's own mailbox yes
mail:draft Save a draft in the owner's Drafts mailbox, never sends no
mail:send Send from an address of the owner, see Sender no

Sender

A token with mail:send or mail:draft has a sender mode, chosen when the token is created. It applies to message_send and message_draft alike, and cannot be changed afterwards. Tokens without either scope always use primary.

Sender mode Label in the token form From and envelope sender from_address argument
primary (default) Primary address only The owner's address Refused
fixed A fixed address The owned address chosen at creation Refused, even when it matches
any Any of my addresses from_address, or the owner's address without it Must be an owned address

The sender is also used for the domain of the Message-ID and for the Sent copy or the draft.

Owned addresses, as mailserver-admin counts them:

  • The owner's address, and every alias with exactly that address as a destination. An alias with several destinations counts if one of them is the owner's.
  • Only addresses stored in lower case. from_address itself is compared without regard to case.
  • Not catch-alls, address extensions, chains of aliases or aliases with an external destination, although Postfix accepts some of them on submission.
  • The same for every role: admins and domain admins only send from their own addresses, not from others in their domain.

The sender is checked on every call, before any limit is counted and before anything is sent or saved. When the address of a fixed token is no longer owned, for example because its alias was deleted or changed, the call is refused. The token is not revoked, and works again once the alias is restored. The token list marks it with No longer owned.

whoami returns send_as for tokens with mail:send or mail:draft: mode, address for fixed, and addresses, the owned addresses, for any.

Tools

Which role reaches which tools and objects is listed in User roles. A tool the role does not reach is not listed, and a call is refused.

Tool Scope
whoami (none)
domain_list manage:read
domain_create, domain_delete manage:write
user_list, user_get manage:read
user_create, user_update, user_delete manage:write
alias_list, alias_get manage:read
alias_create, alias_update, alias_delete manage:write
fetchmail_list, fetchmail_get manage:read
fetchmail_create, fetchmail_update, fetchmail_delete manage:write
dkim_status manage:read
dkim_enable, dkim_disable, dkim_recreate_key manage:write
dns_validate manage:read
mailbox_list, message_search, message_get mail:read
message_draft mail:draft
message_send mail:send

whoami is available to every role. MCP_MAIL_READ_ENABLED and MCP_MAIL_SEND_ENABLED switch off the mail tools, and no mail tool takes a mailbox user as an argument. There is no MCP_MAIL_DRAFT_ENABLED: the scope mail:draft is the only gate of message_draft.

Rules for all tools

  • tools/list only shows the tools a token can use, given its scopes, its owner's role and the feature flags. Calls are checked the same way.
  • Missing scopes, denied objects and objects that do not exist all answer Not found or not allowed., so other domains cannot be probed.
  • Password hashes, passwords, fetchmail passwords and DKIM private keys never appear in tool output.
  • Arguments and result fields are named in snake_case.
  • Every mail from message_send and message_draft carries the header X-Mailer: mailserver-admin (https://github.com/jeboehm/mailserver-admin).

Pagination

A limit or offset out of range is refused rather than corrected.

Tools Default limit Maximum
domain_list, user_list, alias_list, fetchmail_list 50 100
mailbox_list 50 100
message_search 20 100
dns_validate, by next_cursor instead of an offset 10 50

Management tools

  • domain_create generates a DKIM key and leaves DKIM disabled. domain_delete only works on a domain without users and aliases.
  • user_create and alias_create default to the domain of the owner. Only admins can choose another domain or set admin.
  • user_update keeps the role and enabled state of the owner's own user. A changed password revokes that user's tokens, including the calling token if the user is its owner. Disabling a user revokes their tokens.
  • user_delete refuses the owner's own user.
  • fetchmail_create and fetchmail_update accept a password that can never be read back.
  • dkim_enable creates a key if the domain has none. dkim_disable keeps the key. dkim_recreate_key only runs with confirm set to true, because the published DNS record stops matching. All DKIM tools report the published record under a DNS budget of 10 seconds: with timed_out set to true, record_found and record_valid are null and nothing is known about the record.
  • dns_validate works through the domains in pages, with a budget of 20 seconds per call. Domains listed in timed_out were not checked, so nothing is known about their records.

Mail read tools

  • Each call opens its own IMAP session as the token's owner and closes it again. The tools do not change flags such as \Seen.
  • message_search returns headers, newest first. message_get returns headers, a text body and a list of attachments without their content. HTML is converted to text, and a body over MCP_MAIL_MESSAGE_MAX_BYTES is cut off and marked with body_truncated.
  • Everything the sender controls is under the key untrusted_external_content, with a notice telling the agent to treat it as data. This does not make it safe, see prompt injection.
  • Disabled and send-only users are refused.
  • There are no tools to move, delete or flag mail, or to download attachments.

Mail send tool

message_send sends a plain text mail from the sender of the token, with Postfix submission as the owner. Attachments are not supported.

Recipients must be plain addresses such as name@example.com. A non-ASCII character before the @ is refused.

Result field Meaning
sent true: the mail has gone out, whatever the rest says
message_id The Message-ID of the mail
recipients All recipients, including bcc
sent_copy.status saved, skipped (send-only user, no copy is kept) or failed (the mail still went out)

A refused or failed send answers with an error message that says whether to retry. After a lost connection the mail may have gone out, and the message says so.

Mail draft tool

message_draft saves a plain text mail from the sender of the token as a draft, and sends nothing. The mail is saved with the flag \Draft in the owner's Drafts mailbox. A person opens it in their mail client, checks it and sends it from there.

  • It takes the same arguments as message_send, including from_address, and the same rules for recipients and the sender apply.
  • Every call creates a new draft. There is no tool to update or delete a draft, and no reply threading: a draft is a new mail, not an answer within a conversation.
  • mail:draft is independent of mail:send. A token with mail:draft alone cannot send.
Result field Meaning
drafted true: the draft exists, so do not call the tool again
message_id The Message-ID of the draft
recipients All recipients, including bcc

A failed call answers with an error message that says whether to retry, and no draft has been saved.

Limits

Limit Variable Default
Parallel IMAP sessions per user MCP_MAIL_MAX_IMAP_SESSIONS 5
Body returned by message_get MCP_MAIL_MESSAGE_MAX_BYTES 65536
Recipients per mail MCP_MAIL_SEND_MAX_RECIPIENTS 20
Size of a sent message MCP_MAIL_SEND_MAX_BYTES 1048576
Sends per hour, per token MCP_MAIL_SEND_TOKEN_LIMIT_PER_HOUR 30
Sends per hour, per user MCP_MAIL_SEND_USER_LIMIT_PER_HOUR 60
Sends per rolling minute, overall MCP_MAIL_SEND_GLOBAL_LIMIT_PER_MINUTE 15
Drafts per hour, per token MCP_MAIL_DRAFT_TOKEN_LIMIT_PER_HOUR 60

All connections to Dovecot and Postfix come from the address of the web container, which Roundcube shares. Dovecot allows 10 connections per user and address, and Postfix 20 connections per minute and client address. A send or draft over a limit is refused before anything is tried, and the message says when to retry.

Audit log

Every tool call writes one JSON record with the message MCP tool call on the channel mcp_audit, to the standard error of the web container.

Field Content
token_id, user_id, user The token and its owner
tool The tool name
target The object the call names, for example domain:example.com, also on a denied call. Empty if it names none
result ok, denied, failed or error
client_ip The client address, which needs TRUSTED_PROXIES behind a proxy
from, recipients, message_id, sent_copy message_send only
from, recipients, message_id, draft_folder message_draft only

The audit log never contains mail bodies, passwords or tokens. The error log is a separate matter, see failing calls.