MCP overview & tools

@postern/mcp is the Model Context Protocol server for Postern. It gives an AI agent a real, persistent mailbox in one tool call — sends and receives, behind a scoped key that expires and revokes on its own. The standout tool is wait_for_email: block until the next matching message lands and get the OTP code and verification link already extracted.

redeem an enrollment key → create_inbox → use it as a sign-up address → wait_for_email → { otp_code, verification_link }

Tools

Every tool is registered with a typed zod input schema and behavioral annotations (readOnlyHint, destructiveHint, …) so hosts can present and gate them correctly.

Tool	What it does	Hint
redeem_enrollment	Exchange an enrollment key (pk_enroll_…) for a scoped agent key (pk_agent_…).	—
create_inbox	Provision a mailbox. Omit username/domain for an instant agent@<label>.mszazu.com.	—
list_inboxes	List the mailboxes this agent owns.	read-only
get_inbox	Fetch one mailbox by id or address.	read-only
delete_inbox	Tear a mailbox down (WildDuck account + ACS sender).	destructive
send_email	Send a new email via the authenticated ACS sender.	—
reply_email	Reply within an existing thread.	—
read_messages	List messages in a mailbox (optionally unread-only).	read-only
list_threads	List conversation threads.	read-only
search	Full-text search across one or all mailboxes.	read-only
wait_for_email	Block until a matching message arrives; return it + extracted otp_code / verification_link.	read-only

The security model — a postern key, not a master key

Don’t hand an MCP host your master key. Hand it a postern key.

The MCP host only ever receives a scoped agent key:

• scoped — carries only its granted capabilities (mailbox:create, mailbox:read, mailbox:send) and, optionally, a fixed set of domains;
• server-enforced — the mailbox counter and revocation live server-side; a cloned key can’t exceed its max_mailboxes;
• revocable — killing one agent’s key never rotates anyone else’s;
• audited — every action is attributed to the token and the agent. server-enforced

This is the deliberate containment of an MCP supply-chain blast radius: no org-wide key ever reaches the model host. See Enrollment tokens & scopes.

Two transports, one binary

Transport	Use it for	Command
stdio	Local hosts: Claude Desktop, Claude Code, Cursor	postern-mcp
HTTP (Streamable)	Hosted: POST /mcp (default :8787)	postern-mcp --http --port 8787

Offline by default

With no POSTERN_API_KEY (and until the Postern REST API ships), the server serves deterministic in-memory fixtures so every tool is fully exercisable — create_inbox, send_email, and wait_for_email all operate on one coherent dataset. Set a real pk_agent_… key (or POSTERN_MOCK=0 once the API is live) to talk to the backend. Mock seams are marked // TODO(wire-api) in the source.

Configuration (environment)

Variable	Default	Purpose
POSTERN_API_BASE_URL	https://api.agents.mszazu.com	Base URL of the Postern REST API.
POSTERN_API_KEY	(empty)	Scoped agent key (pk_agent_…) or enrollment key (pk_enroll_…).
POSTERN_MOCK	(off)	Set 1 to force offline fixtures.
POSTERN_REQUEST_TIMEOUT_MS	30000	Per-request timeout for non-blocking calls.
POSTERN_MAX_WAIT_MS	300000	Upper bound the server allows wait_for_email to block.
PORT / HOST	8787 / 0.0.0.0	--http bind.

Next

• wait_for_email — the blocking primitive, in depth.
• Client configuration — Claude Desktop, Claude Code, Cursor.
• Quickstart · wait_for_email — the OTP flow end to end.