MailSnail

Serveur MCP hébergé qui permet aux agents IA d’envoyer de vraies lettres et des courriers recommandés USPS. Vérifiez l’adresse, prévisualisez une épreuve PDF avec le prix exact, puis envoyez le courrier. Facturé au prix coûtant, adresses aux États-Unis uniquement. Connectez-vous avec OAuth, rien à installer.

Serveur MCP hébergé

npx add-mcp 'https://api.mailsnail.dev/mcp'

S’installe dans Claude Code, Codex, Cursor et plus

Documentation

Connect Mailsnail to your agent

Two ways to run it. Managed is the one to start with: you sign in, we hold the print-and-mail credentials, and your agent pays from a prepaid balance or for one letter at a time. Self-hosted is for people who already have a Click2Mail or Lob account and would rather use their own.

Steps for your app:Claude ChatGPT Claude Code Cursor VS Code Codex Other apps

Managed — sign in, pay, send

Nothing to install and no keys to paste. The server URL is:

https://api.mailsnail.dev/mcp

Two steps: add it, then start the sign-in from your client — adding a server registers it, but doesn't open the browser on its own.

1. Add the server

The address above is the same everywhere. Claude, Cursor and VS Code take it from a button; the other apps have you paste it:

Claude (every plan, including Free)

  1. Press “Add to Claude”. Claude opens its “Add custom connector” form with the name and the address already filled in. If you are signed out of Claude, it asks you to sign in first.
  2. Press Continue, keep the settings Claude suggests, then press Add.
  3. Sign in when Claude asks. The first time, you create your Mailsnail account on the page that opens.

Add to Claude

A Free account can hold one custom connector. If the button does not open the form, add it by hand: in Claude, open Customize, then Connectors, press “+ Add”, then “Add custom connector”, and paste the address. Adding a connector from Claude’s phone app is in beta: if the form does not appear on your phone, add it once on a computer, and it is in the Claude app on your phone from then on. On Team and Enterprise an owner has to add it first. The owner adds it under Organization settings, then Connectors. Members then open Customize, then Connectors, and press Connect.

Menus move. These steps were checked against Claude’s help page on custom connectors on November 16, 2026.

ChatGPT (on the web, and not on every plan)

  1. On chatgpt.com in a browser, open Plugins. The mobile app cannot add a server.
  2. Press the plus button, then “Add custom MCP server”.
  3. Name it Mailsnail and paste the address as the server URL. Choose OAuth for authentication, tick “I understand and want to continue”, and press “Create as a plugin”.
  4. Install the plugin it creates, and sign in when the Mailsnail page opens. Then, in a new chat, type @ and choose Mailsnail.

Open ChatGPT’s Plugins page

OpenAI decides which plans can add a custom server, and that changes. Its help page describes it for Business, Enterprise and Edu workspaces, where an admin or owner adds it. If your plus button has no “Add custom MCP server”, your plan does not include it. Claude’s free plan can add it.

Menus move. These steps were checked against OpenAI’s help page on custom MCP servers on November 14, 2026.

Claude Code

  1. Run this command in a terminal.
  2. In Claude Code, run /mcp, choose mailsnail, then Authenticate, and sign in on the page that opens.
claude mcp add -t http mailsnail https://api.mailsnail.dev/mcp

Keep the -t http: this is a server we run, not a package to install.

Cursor

  1. Press “Add to Cursor”. Cursor opens and asks whether to install the server; say yes.
  2. Sign in when Cursor asks. The first time, you create your Mailsnail account on the page that opens.

Add to Cursor

If the button does nothing, add the server by hand: put the JSON block further down this page in ~/.cursor/mcp.json, or in.cursor/mcp.json inside one project.

Menus move. These steps were checked against Cursor’s page on MCP install links on November 17, 2026.

VS Code

  1. Press “Add to VS Code”, or run this command in a terminal. VS Code shows the server so you can check it; press Install.
  2. A browser window opens for sign-in the first time the server connects. The first time, you create your Mailsnail account there.

Add to VS Code

code --add-mcp '{"name":"mailsnail","type":"http","url":"https://api.mailsnail.dev/mcp"}'

Menus move. These steps were checked against VS Code’s guide to MCP servers on November 15, 2026.

Codex

  1. Run the first command in a terminal to add the server.
  2. Codex may open the sign-in page right away. If it does not, run the second command. The first time, you create your Mailsnail account on that page.
codex mcp add mailsnail --url https://api.mailsnail.dev/mcp
codex mcp login mailsnail

Menus move. These steps were checked against OpenAI’s page on MCP servers in Codex on November 15, 2026.

Gemini, Perplexity, Mistral Le Chat, Grok

  1. Look for “custom connector” or “add MCP server” in the app’s connectors or apps settings.
  2. Paste the address and sign in.

These apps do not review custom connectors, so you are connecting directly to us.

Any other app that takes a JSON config uses the url form, and so does Cursor if you would rather add it by hand:

{
  "mcpServers": {
    "mailsnail": {
      "url": "https://api.mailsnail.dev/mcp"
    }
  }
}

2. Sign in

There is no sign-up or login page on this website. You create your Mailsnail account the first time your app signs in: the app opens our sign-in page in your browser, and you sign in or create an account there with an email and a password. After that the app keeps itself signed in, and your balance, your payment links and your letters are all one question to the app away (“what is my Mailsnail balance?”). If it ever lists Mailsnail as signed out, signing in again takes a few seconds.

The server answers an unauthenticated call with a standard OAuth challenge, so your client knows where to send you and registers itself. You just approve it in the browser. If the app lists the server as added and not yet connected, start the sign-in from its list of MCP servers: in Claude Code that is /mcp, in Cursor the Customize page.

# In Claude Code, open the MCP panel:
/mcp

# Select "mailsnail" -> Authenticate.
# Your browser opens our sign-in page. Sign in (or create an
# account), approve access, and the tab hands the session back.
# "mailsnail" then reads: connected.

Sign-in is email and password today. The account your agent authenticates against is the account: nothing else has to be set up before the first letter.

If the app says Mailsnail is signed out

A sign-in is short-lived, and the app renews it by itself. Now and then an app does not, most often after it has sat open and idle, and it then lists Mailsnail as signed out, failed or needing a login. Nothing has happened to your account: your balance, your payment links and your letters are kept on our side, not in the app. Sign in again and carry on where you were.

  • Claude: Open Customize, then Connectors, disconnect Mailsnail and connect it again.
  • Claude Code: Run /mcp, choose mailsnail, then Authenticate.
  • Cursor: Open Customize in the sidebar (in older versions, Cursor Settings and then MCP), switch mailsnail off and back on, and sign in if the browser opens.
  • VS Code: Run “MCP: List Servers” from the Command Palette, choose mailsnail, then Restart Server, and sign in if VS Code asks.
  • Codex: Run codex mcp login mailsnail in a terminal.

3. Send something — and pay when asked

You do not have to fund anything up front. The first send tells you what it needs and hands back two links: one to pay for just that letter, one to add funds to your balance.

You: Ask your agent to mail something. For example —
     "Send a letter to Jane Doe at 1 Main St, Brooklyn NY 11201
      that says: thanks for the referral."

Agent: calls preview_letter -> shows you a proof PDF and the price
Agent: calls send_letter   -> { "error": "payment_setup_required",
                                "pay_per_letter_url": "https://checkout.stripe.com/...",
                                "pay_per_letter_cents": 151,
                                "setup_url": "https://checkout.stripe.com/..." }

You: open one of the two links and pay. Both are one-time payments
     and your card is not saved. Stripe handles the card; we never
     see the number.
       pay_per_letter_url  pay for just this letter by card
                           ($1.51 for a one-page first-class letter)
       setup_url           add funds to your balance ($25 by default);
                           letters then cost less ($1.21)

Agent: retry send_letter   -> { "id": "...", "status": "queued" }

Things to ask

  • “Mail a thank-you letter to Jane Doe at 1 Main St, Brooklyn NY 11201. Show me the proof and price before sending.”
  • “Send a certified letter with a return receipt to my tenant at 22 Oak Ave, Austin TX 78701 giving 30 days’ notice. I need the green card back.”
  • “Check whether 1600 Pennsylvania Ave NW, Washington DC 20500 is a deliverable address.”
  • “How much balance do I have left? If auto-reload is on, turn it off.”
  • “What happened to the letter I sent yesterday? Here’s the receipt token.”

Why a letter costs less from a balance than by card

Card processing costs 2.9% plus a fixed 30¢ on every charge. Pay for a single letter by card (pay_per_letter_url) and that one charge carries the whole fee, so a one-page first-class letter costs $1.51 instead of $1.21. Funding a balance once (setup_url) and drawing mail against it spreads the fee over many letters, which is what keeps cheap mail cheap. Both prices are at our cost. Both links are one-time payments: we don't save your card or charge it again. If you want the balance to refill itself, ask your assistant to set up auto-reload. Stripe's page then saves your card and shows the terms (by default, $25 whenever the balance falls below $10), and you agree by paying. You can turn it off any time by asking your assistant (turn_off_auto_reload) or emailing hello@mailsnail.dev. More on billing.

Tools your agent gets in managed mode

  • verify_address — USPS address validation. Free: never charges, never mails.
  • preview_letter — Proof PDF plus the exact price, without charging or mailing. Shows both prices: amount_cents (from your balance) and pay_per_letter_cents (paying for just that letter by card). The usual first step.
  • send_letter — Mails a letter, drawn against your balance. If the balance can’t cover it, it returns two Stripe links: pay_per_letter_url (pay for just that letter by card) and setup_url (add funds). Add extra_service: "certified" for tracking. Paid and irreversible, so your client asks before it runs.
  • get_balance — Your balance, saved card, and auto-reload settings. Free.
  • add_payment_method — Returns a Stripe link to add funds. By default it is a one-time payment and your card is not saved; with auto_reload: true it also saves the card for auto-reload. If a card is on file it also returns a billing-portal link. Charges nothing by itself.
  • turn_off_auto_reload — Turns off automatic charges to your saved card and keeps the card on file. Free. On a team account, only an organization admin can use it.
  • get_letter — Delivery status for a letter, with the USPS tracking number for certified mail. Free.
  • cancel_letter — Cancel a letter before printing starts (usually within about a day) and get its full price back on your balance.

send_postcard and get_postcard are temporarily unavailable.

list_letters is not available in managed mode. It exists only on the self-hosted path below, where the underlying provider account is yours.

What a piece costs

from $1.21

First-class letter

$1.51 for one letter by card

from $8.61

Certified letter

$8.83 for one letter by card

from $11.64

Certified + electronic return receipt

$11.83 for one letter by card

from $14.27

Certified + green-card return receipt

$14.42 for one letter by card

Priced at our cost. The large price is drawn from your balance; the smaller one is what you pay to cover just one letter by card, which is a little higher because that single payment carries Stripe's whole processing fee. These are one-page, black-and-white prices; extra pages and color are priced at our cost. Ask your agent to call preview_letter and it will quote the exact price before anything is charged.

Self-hosted — bring your own mail provider

Run the open-source server yourself against your own Click2Mail or Lob account. There is no sign-in and no balance: your provider bills you directly, and we are not in the payment path at all. This is the mailsnail npm package over stdio.

Claude Code

claude mcp add mailsnail \
  -e MAIL_PROVIDER=click2mail \
  -e CLICK2MAIL_USERNAME=your-username \
  -e CLICK2MAIL_PASSWORD=your-password \
  -- npx -y mailsnail

Claude Desktop and Cursor

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config). Cursor: ~/.cursor/mcp.json or the project's .cursor/mcp.json. Needs Node.js 18+.

{
  "mcpServers": {
    "mailsnail": {
      "command": "npx",
      "args": [
        "-y",
        "mailsnail"
      ],
      "env": {
        "MAIL_PROVIDER": "click2mail",
        "CLICK2MAIL_USERNAME": "your-username",
        "CLICK2MAIL_PASSWORD": "your-password"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml.

[mcp_servers.mailsnail]
command = "npx"
args = ["-y", "mailsnail"]

[mcp_servers.mailsnail.env]
MAIL_PROVIDER = "click2mail"
CLICK2MAIL_USERNAME = "your-username"
CLICK2MAIL_PASSWORD = "your-password"

Set MAIL_PROVIDER=lob with LOB_API_KEY to use Lob instead. Self-hosted mode adds list_letters (Lob only — Click2Mail has no list endpoint), and cancel_letter works against your own provider account within its window. Source and provider docs are on GitHub.

HTTP API, no account

There is also an anonymous path for agents that can pay for themselves: post a letter, get a 402 with the price, retry with a Stripe Shared Payment Token for that amount. The quoted amount is the single-letter card price, which includes Stripe's fee. No sign-in, no balance, no account on our side.

Worth being straight about the tradeoff: most coding agents, including Claude Code, cannot mint a Shared Payment Token on their own today. If yours can't, use managed mode above — that is precisely the gap it was built to close. Settlement in USDC over x402 is planned, not shipped.

# Anonymous, no account: quote first, then pay for that exact piece.
# Your client has to be able to produce a Stripe Shared Payment Token.

curl -X POST https://api.mailsnail.dev/v1/letters \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "name": "Jane Doe",
      "address_line1": "1 Main St",
      "address_city": "Brooklyn",
      "address_state": "NY",
      "address_zip": "11201"
    },
    "from": { "…same shape…": "" },
    "body_text": "Hello from your agent."
  }'

# -> 402 Payment Required
# {
#   "status": 402,
#   "payment_request": {
#     "amount": 151, "currency": "usd", "methods": ["stripe.spt"],
#     "idempotency_key": "…"
#   }
# }
# 151 is the card price for one page of first-class mail. The price from
# a balance is lower; preview_letter returns both (amount_cents and
# pay_per_letter_cents).

# Retry the identical request with a token for the quoted amount:
#   "payment_token": "spt_…"
# -> 200 { id, status, receipt_url }

Machine-readable everything

Full tool schemas live in /llms-full.txt and /openapi.json. If a model is reading this page cold, those are the two files it wants.

Stuck? Email hello@mailsnail.dev.