Setup — wire Mailsnail into your agent

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config). Requires Node.js 18+.

json

{
  "mcpServers": {
    "mailsnail": {
      "command": "npx",
      "args": [
        "-y",
        "physical-mail-mcp"
      ],
      "env": {
        "MAIL_PROVIDER": "managed",
        "MAIL_API_BASE_URL": "https://api.mailsnail.dev"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json or your project's .cursor/mcp.json.

json

{
  "mcpServers": {
    "mailsnail": {
      "command": "npx",
      "args": [
        "-y",
        "physical-mail-mcp"
      ],
      "env": {
        "MAIL_PROVIDER": "managed",
        "MAIL_API_BASE_URL": "https://api.mailsnail.dev"
      }
    }
  }
}

OpenAI Agents SDK

Wire the stdio MCP server into your Agent.

python

from agents import Agent, MCPServerStdio

mail = MCPServerStdio(
    name="mailsnail",
    params={
        "command": "npx",
        "args": ["-y", "physical-mail-mcp"],
        "env": {
            "MAIL_PROVIDER": "managed",
            "MAIL_API_BASE_URL": "https://api.mailsnail.dev",
        },
    },
)

agent = Agent(
    name="Mailer",
    instructions="You can send physical mail via the Mailsnail MCP server.",
    mcp_servers=[mail],
)

HTTP API (no MCP)

Skip MCP and call the underlying API directly via the Machine Payments Protocol.

bash

# Skip MCP — call the HTTP API directly.
# Two-call flow: (1) get a quote / payment challenge, (2) retry with an SPT.

# 1. Get a 402 challenge with the quoted price.
curl -X POST https://api.mailsnail.dev/v1/letters \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "name": "Recipient Name",
      "address_line1": "1 Main St",
      "address_city": "Brooklyn",
      "address_state": "NY",
      "address_zip": "11201"
    },
    "from": { /* same shape */ },
    "body_text": "Hello from your agent.",
    "extra_service": "certified"
  }'
# → 402 Payment Required, WWW-Authenticate: Payment ...

# 2. Retry with a Stripe Shared Payment Token in the body.
curl -X POST https://api.mailsnail.dev/v1/letters \
  -H "Content-Type: application/json" \
  -d '{
    ...same letter...,
    "payment_token": "spt_..."
  }'
# → 200 { id, status, payment_intent_id, receipt_url }

What your agent can now do

After connecting, the agent has these tools available:

verify_address — USPS CASS validation. Free. Run before sending.
send_letter — mail a physical letter. Pass body_text (we render the PDF) or file_url (your own PDF).
send_postcard — send a postcard with a custom front and back.
get_letter — check delivery status by ID.
list_letters — list everything the agent has sent.
cancel_letter — cancel before production. Short window.

Full schemas live in /llms-full.txt and /openapi.json.

How payment works

There's no account on our side. When the agent calls send_letter, the server returns a 402 with the quoted price. The agent mints a Stripe Shared Payment Token (SPT) from a Link wallet (or via the link-cli) and retries with the SPT. We charge once and mail. If mailing fails, the charge is auto-refunded.

Wire Mailsnail into your agent