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:

npm install
npm run server

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

{
  "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:

https://postalform.com/mcp

For most agents, the default pattern should be:

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:

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	Claude Desktop and Claude Code setup for a local agent-mail MCP server
examples/02-send-a-letter	Creating an unpaid PostalForm checkout draft for one letter
examples/03-x402-paywalled-send	Validate-first x402 and MPP machine-order payloads
examples/04-langchain-tool	Wrapping PostalForm validation as a LangChain-style tool
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:

npm run check:discovery

Repository Map

Path	Purpose
src/server.mjs	Local stdio MCP server for agent-mail discovery, validation, and unpaid checkout drafts
.well-known/mcp.json	Repo-level MCP discovery descriptor
manifest/mcp-server.json	Directory-ready local MCP server descriptor
manifest/x402-payment.json	x402 physical mail payment descriptor
docs/quickstart.md	First-run guide
docs/tools-reference.md	Tool behavior and side-effect reference
docs/machine-payments.md	MPP and x402 guidance
docs/compliance.md	Abuse, privacy, and approval guidance
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), who also maintains rrule-temporal.

License

MIT