MCP Server (AI Agents)
The Papercut SMTP Service includes an optional Model Context Protocol (MCP) server that lets AI agents and coding assistants — Claude Code, and any other MCP-capable client — inspect the email your application sends during development.
A typical agent-driven test loop:
- The agent triggers your app to send an email
list_messages— confirm it arrived (searchnarrows it to the one you're after, e.g. by recipient or a code in the body)get_message— assert on subject, recipients, and bodyget_message_section— verify an attachment's actual contentdelete_all_messages— reset for the next test
Off by default
The MCP server is disabled unless you explicitly enable it. The service logs its status at startup either way:
Enabling
Set EnableMcpServer to true using any of the service's configuration layers:
Restart the service after changing it. When enabled, the endpoint is served at:
In the desktop app, turn on MCP under Options and restart Papercut instead. Its endpoint is normally http://127.0.0.1:37410/mcp.
(Streamable HTTP transport; the path respects HttpPathPrefix if configured.) The web UI shows an MCP badge in the navigation bar when the server is on — hover it for the endpoint URL, click to copy. The URL is also available programmatically at GET /api/mcp, which — like all API routes — is relative to the service base URL including any HttpPathPrefix, and returns the full endpoint URL with the prefix applied.
Connecting a client
MCP clients that run in a web page, such as a browser-based inspector, need their origin listed in CorsAllowedOrigins. Clients that run as a program, including Claude Code, aren't affected unless they connect by a public host name.
Claude Code:
Generic MCP client configuration:
Tools
| Tool | Description |
|---|---|
list_messages |
Paged message summaries, newest first (limit, start). search finds messages containing every word anywhere: subject, addresses, body or attachment names |
get_message |
Full detail for one message: from/to/cc/bcc, subject, text and HTML bodies, headers, and a manifest of MIME sections (index, contentId, media type, filename, attachment flag, size) |
get_message_section |
Decoded content of a single MIME part, selected by index or contentId from the manifest — text parts return as text, binary parts as base64 |
get_message_raw |
The raw RFC 822 (.eml) source of a message |
create_message |
Create a message directly, without SMTP, as markdown, html or text. It notifies like received mail, so an agent can use it to tell you something; notify: false only adds it to the inbox |
delete_message |
Delete one message by id |
delete_all_messages |
Clear the message store |
Large content is truncated to keep responses manageable (raw messages at 200K characters, binary sections at 512KB) with a truncated flag pointing to the full-content REST endpoints (/api/messages/{id}/raw and /api/messages/{id}/sections/{index}).
Network exposure
Like the REST API and web UI, the MCP endpoint has no built-in authentication — anyone who can reach the HTTP port can read and delete messages. Keep the binding on localhost, or put a reverse proxy with auth in front of it. See the network exposure warning.