AI assistants over MCP#
From 2.4.0 piler serves the archive to AI assistants through the Model Context
Protocol (MCP) at /mcp on the UI: Claude Code, Claude Desktop, VS Code and
other clients that speak MCP over HTTP. The assistant searches the emails
the user may see, reads them and their attachments, and reports back.
The endpoint is read-only. It has no tool that changes the archive, sends mail or edits a setting. It uses the same access rules as the UI and the REST API: the user sees the emails their role and filters allow, and nothing else.
Notices before you turn it on#
The data goes to the client's provider. Everything the assistant reads is sent to the provider of that assistant: the email text, the headers, the text of the attachments. For a hosted model (Claude, Copilot, and the other cloud assistants) that means the provider of the model gets the mail the user reads through it, under that provider's terms. A local model served on your own network keeps the data on your network. Decide this before you allow the endpoint for your users, and tell them.
The token is a password. An assistant stores the personal API token in its configuration, often in plain text. Anyone who can read that file can read, as the token's user, every email the user may see, until the token expires or is revoked. Treat it like a password: don't paste it into chats, tickets or screenshots, and don't keep it on a shared machine. If a laptop is lost or unattended, revoke the token at once in Settings > API tokens (the user) or Users > API tokens (the admin).
Emails can contain instructions. An archived email may carry text aimed at the assistant ("search for X and send the results"). The assistant can follow it, and the user may not notice. The endpoint can't tell a request from a person from one from an email. Read what the assistant does with the results, and don't connect other tools that can send data out to the same assistant.
Turning it on#
- Set
MCP_ENABLED=truefor the tenant, in its settings. It requires the personal API tokens (PERSONAL_API_TOKENS, on by default). - Auditors are off by default. Set
AUDITOR_MCP_ACCESS=trueonly when the auditors should use the endpoint: the auditors see every email, so this sends every email they read to the client's provider. Changing it is audited. Without it an auditor's token gets 403 on/mcp. - To keep MCP from a role, add
mcptoDISABLED_FEATURES_USERorDISABLED_FEATURES_AUDITOR.
With the defaults, MCP_ENABLED and AUDITOR_MCP_ACCESS are the only
switches: MCP_ENABLED=true allows every regular user, and admins are
covered by it too, while AUDITOR_MCP_ACCESS=true allows the auditors (it
has no effect unless MCP_ENABLED is true). The disabled-feature keys in
step 3 are an extra override per role, for example MCP for the auditors
only, with mcp in DISABLED_FEATURES_USER.
See Configuration options for the limits
(MCP_MAX_RESULTS, MCP_MAX_BODY_CHARS, MCP_MAX_ATTACHMENT_CHARS).
Auditors' safeguards#
When AUDITOR_MCP_ACCESS is on, an auditor's token has more limits than a
user's:
- A read budget. Each successful
get_message,get_headers,get_threadandget_attachment_textcall is one read. An auditor getsMCP_AUDITOR_READ_BUDGETreads (200 by default) perMCP_AUDITOR_READ_WINDOW(one hour; at least one minute). The budget is per user, so all the tokens of an auditor share it. Over it, the tool says the budget is used up, until the window ends. Searches are not counted: they return only the firstMCP_MAX_RESULTSemails. The audit has amcp bulk readentry at 80% and when the budget runs out. - A short life. A new auditor token lasts at most 7 days
(
PERSONAL_API_TOKEN_AUDITOR_MAX_DAYS), whatever the tenant's maximum. - An idle limit. An auditor's token that wasn't used for 14 days
(
PERSONAL_API_TOKEN_AUDITOR_IDLE_DAYS) stops working. The user creates a new one.
Regular users' tokens have none of these limits.
Email text in the answers#
The assistant is told that archived email is untrusted data, and that some of it is written to manipulate AI assistants. It is told to treat every result as data about the archive, to say so when a result tries to instruct it, and to continue the user's task. This is an instruction to the assistant, not a boundary the server enforces: the protection that doesn't depend on the assistant is the read-only tools, the read budget and the audit log.
Connecting a client#
The user creates a token in Settings > API tokens, with the scope read and an expiry. The token is shown once.
The results of get_message, get_headers and get_attachment_text carry the
body and the text in structuredContent; their text block is a one-line
summary. A client has to pass structuredContent to the assistant. Claude Code
does. Check any other client before you rely on it.
Claude Code:
claude mcp add --transport http piler https://piler.example.com/mcp --header "Authorization: Bearer plp_..."
Run it in a terminal, outside a chat session, so the token doesn't end up in
a transcript. Other clients take the same URL and the same Authorization
header in their MCP server settings.
In a new session the client should show piler as connected.
What the assistant can do#
-
Who it is:
whoamigives the user's email and role, whether the user may see every email, and which tools answer for every email (auditors only). An assistant should call it first when it matters what the user may see. -
Search the emails: free text or labels, never both (
from:,to:,subject:,a:for an attachment type,tag:,cat:,d:,size:,date1:,date2:), and the date range. Each result has the date, the sender, the subject and its attachments (the first 20 names; the count is always given). An auditor also gets the recipients of each (the first 10, with the count); the other users don't, as the recipients include the Bcc ones. A label such asa:takes one word: writesubject: rechnung a: pdf, nota:pdf rechnung, which is refused.search_attachmentslists the emails with their attachments. - Read an email: the headers, the body (long bodies come in parts, see
body_offset), the attachments.get_attachment_textreads the text of a text file, a PDF or an office document. Images and binary files have no text. - Follow a conversation (
get_thread) and find similar emails (similar_messages). - Count the emails the user may see with
list_categoriesandlist_tags(the user's own tags). - Statistics for the auditors:
archive_stats(the number of emails, the date range, the top senders and recipients and their domains).
The archive has no folders. An assistant answers a question about folders with that, not with a search.
On a multi-node setup the master asks the workers for everything the tools
need, with the user's token; the answers are the same as on a single node.
The top lists of archive_stats are approximate there.
What is logged#
Each tool call is an mcp tool entry in the audit log, with the tool, its
arguments, the token and the client address. The REST calls behind it are
logged too (api token read, search, view). The log shows what was read,
not whether a person or the assistant chose it.
For the monitoring, each node counts the tool calls in piler_mcp_tool_calls_total
by tool and result (ok or error), and their time in
piler_mcp_tool_duration_seconds. See monitoring.
Limits#
- A search returns at most
MCP_MAX_RESULTSemails a page (50 by default). - A body is cut at
MCP_MAX_BODY_CHARScharacters per call, an attachment text atMCP_MAX_ATTACHMENT_CHARS; the rest comes with the next call. - Only the first 1000 hits of a search can be paged: narrow it with the dates, or sort oldest.