# MCP overview & tools

{/* // SCOPED EMAIL FOR AGENTS */}

`@postern/mcp` is the [Model Context Protocol](https://modelcontextprotocol.io) 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`](https://docs.agents.mszazu.com/mcp/wait-for-email/): block until the next matching message lands and get the OTP
code and verification link already extracted.

```text
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](https://zod.dev) 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](https://docs.agents.mszazu.com/concepts/enrollment-tokens/).

## 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](https://docs.agents.mszazu.com/mcp/wait-for-email/) — the blocking primitive, in depth.
- [Client configuration](https://docs.agents.mszazu.com/mcp/client-configuration/) — Claude Desktop, Claude Code, Cursor.
- [Quickstart · wait_for_email](https://docs.agents.mszazu.com/quickstart/wait-for-email/) — the OTP flow end to end.