Skip to content

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#

  1. Set MCP_ENABLED=true for the tenant, in its settings. It requires the personal API tokens (PERSONAL_API_TOKENS, on by default).
  2. Auditors are off by default. Set AUDITOR_MCP_ACCESS=true only 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.
  3. To keep MCP from a role, add mcp to DISABLED_FEATURES_USER or DISABLED_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_thread and get_attachment_text call is one read. An auditor gets MCP_AUDITOR_READ_BUDGET reads (200 by default) per MCP_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 first MCP_MAX_RESULTS emails. The audit has a mcp bulk read entry 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: whoami gives 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 as a: takes one word: write subject: rechnung a: pdf, not a:pdf rechnung, which is refused. search_attachments lists the emails with their attachments.

  • Read an email: the headers, the body (long bodies come in parts, see body_offset), the attachments. get_attachment_text reads 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_categories and list_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_RESULTS emails a page (50 by default).
  • A body is cut at MCP_MAX_BODY_CHARS characters per call, an attachment text at MCP_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.