# agent-mail-mcp - Send physical mail from an AI agent

An open MCP server for physical mail. Use PostalForm to create reviewable mail drafts, hosted checkout sessions, validate-only quotes, and explicitly approved agent-payable mail through MPP (Machine Payment Protocol) or x402 physical mail.

This repo is the reference implementation and example pack for terms like "send physical mail from an AI agent", "MCP server for physical mail", "agent-payable mail", "x402 physical mail", "pay for mail with x402", and "MPP mail".

## Quick Start

Run the local stdio MCP server:

```bash
npm install
npm run server
```

Or configure an MCP client to run it from npm after publication:

```json
{
  "mcpServers": {
    "agent-mail": {
      "command": "npx",
      "args": ["-y", "@postalform/agent-mail-mcp"]
    }
  }
}
```

The local server exposes safe agent-mail tools:

| Tool | Purpose | Side effect |
| --- | --- | --- |
| `agent_mail_discovery` | Returns PostalForm MCP, OpenAPI, x402, A2A, and docs URLs | Read-only |
| `list_postalform_tools` | Lists live PostalForm remote MCP tools | Read-only |
| `validate_letter_mail` | Validates and quotes a letter machine-order payload | No payment, printing, or mailing |
| `create_letter_checkout_draft` | Creates an unpaid hosted-checkout draft | No mail is sent until checkout is reviewed and paid |

## Remote PostalForm MCP

If your client supports remote streamable HTTP MCP servers, you can connect directly:

```text
https://postalform.com/mcp
```

For most agents, the default pattern should be:

```text
draft -> preview -> approve/pay -> send -> track
```

Hosted checkout is the safer default for chat-style assistants because the owner reviews the PDF, sender, recipient, mailing options, and price before PostalForm prints or posts real mail. The local `confirm_create_unpaid_draft` flag is a soft client-side guard for creating an unpaid draft, not proof of human payment approval.

## Validate Before Paying

Validate a machine-order payload without sending mail:

```bash
POSTALFORM_VALIDATE_EXAMPLE=1 npm run rest:validate-letter
```

Direct MPP (Machine Payment Protocol) or x402 machine payment should only be used when the runtime already has explicit owner approval, a spend limit, and retry-safe request IDs.

## Examples

| Path | What it demonstrates |
| --- | --- |
| [examples/01-claude-mcp](examples/01-claude-mcp) | Claude Desktop and Claude Code setup for a local agent-mail MCP server |
| [examples/02-send-a-letter](examples/02-send-a-letter) | Creating an unpaid PostalForm checkout draft for one letter |
| [examples/03-x402-paywalled-send](examples/03-x402-paywalled-send) | Validate-first x402 and MPP machine-order payloads |
| [examples/04-langchain-tool](examples/04-langchain-tool) | Wrapping PostalForm validation as a LangChain-style tool |
| [examples/05-openai-responses-mcp](examples/05-openai-responses-mcp) | OpenAI Responses API remote MCP configuration |

## Discovery

Canonical PostalForm URLs:

| Field | URL |
| --- | --- |
| MCP endpoint | `https://postalform.com/mcp` |
| Developer docs | `https://postalform.com/developers` |
| Agent guide | `https://postalform.com/agents` |
| OpenAPI | `https://postalform.com/openapi.json` |
| MCP registry manifest | `https://postalform.com/.well-known/mcp/server.json` |
| MCP server card | `https://postalform.com/.well-known/mcp/server-card.json` |
| A2A Agent Card | `https://postalform.com/.well-known/agent-card.json` |
| x402 discovery | `https://postalform.com/.well-known/x402` |
| LLM overview | `https://postalform.com/llms.txt` |

Run the live discovery check:

```bash
npm run check:discovery
```

## Repository Map

| Path | Purpose |
| --- | --- |
| [src/server.mjs](src/server.mjs) | Local stdio MCP server for agent-mail discovery, validation, and unpaid checkout drafts |
| [.well-known/mcp.json](.well-known/mcp.json) | Repo-level MCP discovery descriptor |
| [manifest/mcp-server.json](manifest/mcp-server.json) | Directory-ready local MCP server descriptor |
| [manifest/x402-payment.json](manifest/x402-payment.json) | x402 physical mail payment descriptor |
| [docs/quickstart.md](docs/quickstart.md) | First-run guide |
| [docs/tools-reference.md](docs/tools-reference.md) | Tool behavior and side-effect reference |
| [docs/machine-payments.md](docs/machine-payments.md) | MPP and x402 guidance |
| [docs/compliance.md](docs/compliance.md) | Abuse, privacy, and approval guidance |
| [docs/directory-listing.md](docs/directory-listing.md) | Copy-paste directory listing fields |

## Directory-Ready Summary

PostalForm is a remote MCP server and physical-mail API for AI agents. Agents can create reviewable mail drafts from PDFs, text, HTML, Markdown, RTF, or form payloads, return hosted checkout for human approval, or use owner-approved MPP/x402 machine-payment flows to pay for and track real postal mail.

## Safety Defaults

- Prefer hosted checkout for chat-style agents.
- Require approval before sharing private documents, addresses, or payment credentials.
- Use stable `request_id` values for direct machine-payment retries.
- Show a PDF preview when available before payment.
- Enforce spend limits outside the model prompt.
- Do not use PostalForm for spam, harassment, illegal content, checks, keys, packages, notarization, process serving, or legal advice.

## Maintainers

Maintained by PostalForm and Gabriel Garrett ([`ggaabe`](https://github.com/ggaabe)), who also maintains [`rrule-temporal`](https://www.npmjs.com/package/rrule-temporal).

## License

MIT