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_addressitself 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/listonly 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_sendandmessage_draftcarries the headerX-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_creategenerates a DKIM key and leaves DKIM disabled.domain_deleteonly works on a domain without users and aliases.user_createandalias_createdefault to the domain of the owner. Only admins can choose another domain or setadmin.user_updatekeeps the role andenabledstate 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_deleterefuses the owner's own user.fetchmail_createandfetchmail_updateaccept a password that can never be read back.dkim_enablecreates a key if the domain has none.dkim_disablekeeps the key.dkim_recreate_keyonly runs withconfirmset totrue, because the published DNS record stops matching. All DKIM tools report the published record under a DNS budget of 10 seconds: withtimed_outset totrue,record_foundandrecord_validarenulland nothing is known about the record.dns_validateworks through the domains in pages, with a budget of 20 seconds per call. Domains listed intimed_outwere 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_searchreturns headers, newest first.message_getreturns headers, a text body and a list of attachments without their content. HTML is converted to text, and a body overMCP_MAIL_MESSAGE_MAX_BYTESis cut off and marked withbody_truncated.- Everything the sender controls is under the key
untrusted_external_content, with anoticetelling 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, includingfrom_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:draftis independent ofmail:send. A token withmail:draftalone 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.