Skip to content

FOR AGENT BUILDERS

Physical mail for AI agents

PaperAgent lets an AI agent mail one real paper letter to a US address through USPS. The agent drafts the letter and shows the person a PDF preview and the exact total; the person approves it and pays on a payment link; we print it in New York and hand it to USPS. Connect over MCP or call the REST API — both run the same letter service.

Add to ClaudeAdd to ChatGPT

Building your own client? The API and MCP reference has every tool, endpoint and permission.

Approve, then pay

Every letter goes through the same steps, and the person is in the two that matter: approving the letter and paying for it.

  1. 01get_pricing, and validate_address for any address a person typed. Neither needs sign-in.
  2. 02create_draft with the recipient and a plain-text or Markdown body. It holds the content and the price for 24 hours and mails nothing.
  3. 03preview_draft: show the person the PDF and the exact total. Change anything with update_draft and preview again.
  4. 04Once the person approves, call send_letter with that total as confirm_total_cents and an idempotency_key you generate once. It answers with a payment link for the person, and charges nothing itself.
  5. 05The person pays on the Stripe page, and only then is the letter printed and mailed. Follow it with get_letter_status.

Connect over MCP

The endpoint is https://paperagent.dev/mcp, over streamable HTTP. Sign-in is OAuth: the person enters their email and the six-digit code we send. get_pricing and validate_address answer without signing in; every other tool asks for sign-in the first time it is called, and needs letters:read or letters:write.

The eight tools

get_pricing
The published price list: each product on sale and its price, in US cents.
No sign-in
validate_address
Checks a US street address and returns the normalized form the envelope is printed with, plus any corrections.
No sign-in
create_draft
Creates a draft from the recipient and a plain-text or Markdown body, and returns its page count and total. Mails nothing.
Sign-in · letters:write
update_draft
Changes the recipient, body or service of an unsent draft and prices it again.
Sign-in · letters:write
preview_draft
Returns the PDF preview and the current total — the number send_letter needs as confirm_total_cents.
Sign-in · letters:read
send_letter
Turns an approved draft into an unpaid order and returns a payment link for the person. Nothing prints until it is paid.
Sign-in · letters:write
get_letter_status
Reports where one letter is, its mail date and its estimated delivery date.
Sign-in · letters:read
list_letters
Lists the account’s letters, newest first, with status, mail date and total for each.
Sign-in · letters:read

The input schemas come from tools/list. The tool reference lists each tool with its permission.

REST API and llms.txt

HTTP-only agents use the REST API at https://paperagent.dev/v1, described by openapi.json. It runs the same engine and payment state as MCP: draft, preview, approval, then an unpaid order with a payment link.

/llms.txt is the whole integration in one file — the workflow, current prices, limits and every REST operation — and the docs are the reference.

Limits

  • US addresses only, for the recipient and for the return address.
  • One recipient per letter. There is no bulk or mail-merge endpoint.
  • Up to 6 printed pages, black and white, at the same price: up to 3 print on one side, 4 to 6 on both. A longer body is refused, not billed.
  • Not email, fax or text. The only output is a paper letter in an envelope.
  • Irreversible once printed. There is no tool that calls a letter back.

Prices

  • Standard

    $7.00

  • Certified Mail

    $19.00

Both include email updates. Certified Mail adds USPS tracking and the delivery date and time from the USPS delivery scan; we do not relay a signature or a Return Receipt.

Each price is for one letter of up to 6 printed pages, black and white. Sales tax may apply, and the exact total is shown before you approve.

Read them live from get_pricing or GET /v1/pricing, or on the pricing page.

Already in Claude and ChatGPT

People can use PaperAgent without any code from Claude’s connector directory and ChatGPT’s plugin directory. The guided setup pages show each screen:

Set up ClaudeSet up ChatGPT

Frequently asked questions

What is the PaperAgent MCP endpoint?

https://paperagent.dev/mcp, over streamable HTTP. get_pricing and validate_address work without signing in; the other six tools use OAuth sign-in with an emailed six-digit code.

Can an agent pay for a letter by itself?

No. send_letter returns a payment link for the person, after they have seen the PDF preview and the exact total. Nothing is printed or mailed until that payment completes.

Is there a REST API as well as MCP?

Yes. The REST API at https://paperagent.dev/v1 is described by https://paperagent.dev/openapi.json and runs the same engine and payment state as MCP. https://paperagent.dev/llms.txt has the whole workflow.

Can it send bulk mail or international letters?

No. Each letter goes to one US recipient, up to 6 printed pages in black and white. There is no bulk or mail-merge endpoint and no international mail.

How much does a letter cost through the API?

The current prices are $7.00 for a Standard letter and $19.00 for a Certified Mail letter, plus sales tax where it applies. There is no per-page charge and no volume discount; get_pricing and GET /v1/pricing return the live list. Certified Mail adds USPS tracking and the delivery date and time from the USPS delivery scan; we do not relay a signature or a Return Receipt.

Which assistants can use it already?

Claude and ChatGPT list PaperAgent in their directories, and Muse.ai connects over REST. Any MCP client that supports streamable HTTP and OAuth can use the endpoint directly.

Related guides