# agent-mail — Mail MCP

> `<seat>[+session]@staging.agents.klappy.dev` — read-only mail for agents over MCP; no send path.

Mail for `<seat>[+session]@staging.agents.klappy.dev`. No send path.

## Auth
OAuth as the owner: your MCP client signs you in through Cloudflare Access (your email) on first connect, once per client. A seat is a label you pass and every read is logged; you may read only seats you own (`owners` table). Without a grant, `docs()` answers with `login_url`.

## Tools
- `docs({query?, depth?})` — this pass; deeper rungs; canon via oddkit.
- `execute({method, path, query?, fields?})` — GET/HEAD; one write, POST /admin/seats.
- `telemetry({sql})` — one SELECT over `agent_mail_telemetry`.

## Resources
- `GET /whoami` (any owner)
- `GET /inbox` (owner of seat) — seat, session?, newer_than?, older_than?, from?, subject?, include_expired?, limit?
- `GET /messages/{id}` (owner of the message's seat) — seat?
- `GET /latest` (owner of the address's seat) — to, newer_than?
- `GET /admin/inbox` (admin) — seat?, session?, q?, older_than?, limit?
- `GET /admin/messages/{id}` (admin)
- `GET /admin/delivery` (admin) — to, since?
- `POST /admin/seats` (admin) — seat, owner_email?, retention_days?

## Journeys
- Newest sign-in code for persona+run42 → `execute {method:"GET", path:"/latest", query:{to:"persona+run42@staging.agents.klappy.dev"}}`
- Did an invite arrive (admin) → `execute {method:"GET", path:"/admin/delivery", query:{to:"..."}}`
- Watch one land: mail persona+demo@staging.agents.klappy.dev; `GET /demo/wait?since=<epoch ms>` answers `{address, landed, age_ms, observed_at}` within 25 s, metadata only.

## HUMAN-ONLY
Approve the email allowlist in the Cloudflare Access app (callback `https://staging.agents.klappy.dev/callback`). Vars `ACCESS_ISSUER`, `ACCESS_CLIENT_ID`; Worker secrets `ACCESS_CLIENT_SECRET`, `COOKIE_ENCRYPTION_KEY`.

## Connect
- [MCP endpoint](https://staging.agents.klappy.dev/mcp): streamable HTTP; OAuth as the owner
- [Server card](https://staging.agents.klappy.dev/mcp/server-card): SEP-2127

## Docs
- [Boarding pass](https://staging.agents.klappy.dev/): send `Accept: text/markdown`
- [OpenAPI](https://staging.agents.klappy.dev/openapi.json): HTTP routes; execute paths under x-mcp-execute-paths

## Optional
- [AI catalog](https://staging.agents.klappy.dev/.well-known/ai-catalog.json)
- [mcp.json](https://staging.agents.klappy.dev/.well-known/mcp.json): non-standard alias
- [Live strip](https://staging.agents.klappy.dev/landing/strip.json): counts and ages only