PostalForm MCP

Mail real letters from agents: PDF → checkout → status.

Mail API and Remote MCP Server for AI Agents

PostalForm is a mail API and remote MCP server for turning PDFs, letters, forms, and agent output into real physical postal mail. Developers can create reviewable mail drafts, hosted checkout sessions, direct MPP/x402 machine orders, and fulfillment-status lookups without building print, envelope, postage, or carrier-handoff infrastructure.

Quick answer: can developers send postal mail through an API?

Yes. PostalForm lets developers send postal mail through API and MCP workflows. Use hosted-checkout draft tools when a human should review the PDF, addresses, mailing options, and price before payment. Use direct MPP or x402 machine-payment flows only for autonomous runtimes with explicit owner approval, spending limits, and idempotent request IDs.

Use this table when evaluating PostalForm for an MCP registry, agent directory, API catalog, connector review, or developer-tool listing.

PostalForm is a remote MCP server and physical mail API for creating reviewable print-and-mail drafts from PDFs, letters, and forms, with hosted checkout, fulfillment status, and approved MPP/x402 machine-payment flows.

Which integration surface should you use?

Use these canonical URLs when listing PostalForm in MCP directories, connector catalogs, or agent registries:

- Remote MCP endpoint:https://postalform.com/mcp
- A2A Agent Card:https://postalform.com/.well-known/agent-card.json
- A2A JSON-RPC discovery bridge:https://postalform.com/a2a
- MCP server card:https://postalform.com/.well-known/mcp/server-card.json
- MCP compatibility manifest:https://postalform.com/.well-known/mcp.json
- MCP Registry server manifest:https://postalform.com/.well-known/mcp/server.json
- Agent skill:https://postalform.com/skill.md
- LLM overview:https://postalform.com/llms.txt
- Full LLM content dump:https://postalform.com/llms-full.txt
- Open Knowledge Format index:https://postalform.com/okf/index.md
- APIs.json index:https://postalform.com/apis.json
- API catalog:https://postalform.com/.well-known/api-catalog
- API specification:https://postalform.com/openapi.json
- Agent guide:https://postalform.com/agents
- AI instructions:https://postalform.com/ai

{ "type": "mcp", "server_label": "postalform", "server_description": "Create real PostalForm mail drafts, hosted checkout sessions, machine-payment mail orders, and order status lookups.", "server_url": "https://postalform.com/mcp", "require_approval": "always" }

gemini mcp add --transport http postalform https://postalform.com/mcp

- Discovery profile:https://postalform.com/.well-known/ucp
- UCP MCP endpoint:https://postalform.com/ucp/mcp
- Capability: dev.ucp.shopping.checkout (version 2026-01-11)
- Tools: create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout

{ "name": "create_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "currency": "USD", "line_items": [{ "item": { "id": "postalform_mail_pdf_bw_double" }, "quantity": 1 }], "payment": {}, "metadata": { "postalform": { "pdf": { "download_url": "https://example.oaiusercontent.com/file.pdf", "file_id": "file_abc123" }, "file_name": "letter.pdf", "sender_name": "Sender Example", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_type": "Address", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_type": "Address", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "double_sided": true, "color": false } } } }

- https://postalform.com/mcp
- Methods: POST/GET/DELETE with the streamable HTTP transport
- Sessions: initialize once, then include themcp-session-idheader on all subsequent requests
- Auth: no authentication is required today (contactsupport@postalform.comfor allowlisting)
- Transport: JSON-RPC payloads over POST
- Point your MCP client at /mcp and initialize a session.
- Choose addresses: use Loqate IDs viapostalform.search_addresses, or use manual addresses with_address_type="Manual"+_address_manual(countryCodedefaults toUS).
- Create a draft:

import { Client } from '@modelcontextprotocol/sdk/client/index.js' import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js' const transport = new StreamableHTTPClientTransport(new URL('https://postalform.com/mcp')) const client = new Client({ name: 'my-agent', version: '1.0.0' }) await client.connect(transport) await client.listTools() const draft = await client.callTool({ name: 'postalform.create_letter_order_draft', arguments: { letter: { title: 'Demand for payment', body: 'Hello...\\n\\nThis is my letter body.\\n\\nSincerely,\\n', signature: 'Sender Example', }, sender_name: 'Sender Example', sender_address_type: 'Manual', sender_address_manual: { line1: '123 Sender St', city: 'Springfield', state: 'IL', zip: '62701', }, recipient_name: 'Recipient Example', recipient_address_type: 'Manual', recipient_address_manual: { line1: '456 Recipient Ave', city: 'Springfield', state: 'IL', zip: '62701', }, }, }) console.log(draft.structuredContent?.checkout_url)

{ "name": "postalform.list_forms", "arguments": { "q": "IRS", "limit": 10 } }

{ "name": "postalform.get_form_schema", "arguments": { "slug": "1099-nec" } }

{ "name": "postalform.search_addresses", "arguments": { "target": "recipient", "query": "123 Main St" } }

{ "structuredContent": { "view": "address_suggestions", "target": "recipient", "query": "123 Main St", "suggestions": [ { "id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "text": "123 Main St, Springfield, IL 62701", "type": "Address", "description": "" } ] } }

{ "name": "postalform.create_letter_order_draft", "arguments": { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "letter": { "title": "Payment demand letter", "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n", "signature": "Sender Example" }, "sender_name": "Sender Example", "sender_address_type": "Manual", "sender_address_manual": { "line1": "123 Sender St", "city": "Springfield", "state": "IL", "zip": "62701" }, "recipient_name": "Recipient Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "city": "Springfield", "state": "IL", "zip": "62701" } } }

{ "name": "postalform.create_form_order_draft", "arguments": { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "slug": "1099-nec", "fields": { "calendar_year": "2025", "payer_name": "Sender Example LLC", "payer_street_address": "123 Sender St", "payer_city_state_zip_phone": "Springfield, IL 62701, 217-555-0100", "payer_tin": "12-3456789", "recipient_tin": "123-45-6789", "recipient_name": "Contractor Example", "recipient_street_address": "456 Recipient Ave", "recipient_city_state_zip": "Springfield, IL 62701", "box_1_nonemployee_compensation": "1250.00" }, "sender_name": "Sender Example", "sender_address_type": "Address", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Contractor Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "city": "Springfield", "state": "IL", "zip": "62701" } } }

{ "name": "postalform.create_pdf_upload", "arguments": { "file_name": "letter.pdf", "content_type": "application/pdf", "content_length": 1234567 } }

{ "structuredContent": { "upload_url": "https://postalform.com/api/mcp/pdf-uploads/pfu_...", "upload_token": "pfu_...", "expires_at": "2026-01-17T12:00:00Z", "max_bytes": 104857600, "required_headers": { "Content-Type": "multipart/form-data" } } }

Note:pdfaccepts a ChatGPT file object, anupload_token, or a base64 data URL (data:application/pdf;base64,...). If you pass a URL, it must be https and hosted on an allowlisted domain (default:.oaiusercontent.com). Request:

{ "name": "postalform.create_order_draft", "arguments": { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "pdf": { "upload_token": "pfu_..." }, "file_name": "letter.pdf", "sender_name": "Sender Example", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_type": "Address", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_type": "Address", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "double_sided": true, "color": false } }

{ "structuredContent": { "view": "order_draft", "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "page_count": 2, "price_usd": 2.99, "checkout_url": "https://postalform.com/payment?orderId=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "sender_name": "Sender Example", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "checkout_session": { "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "payment_provider": { "provider": "stripe", "merchant_id": "profile_123", "supported_payment_methods": ["card", "apple_pay", "google_pay"] }, "status": "ready_for_payment", "currency": "usd", "line_items": [ { "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "item": { "id": "postalform_mail_pdf", "quantity": 1 }, "base_amount": 299, "discount": 0, "subtotal": 299, "tax": 0, "total": 299 } ], "totals": [ { "type": "items_base_amount", "display_text": "Items", "amount": 299 }, { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }, { "type": "tax", "display_text": "Tax", "amount": 0 }, { "type": "total", "display_text": "Total", "amount": 299 } ], "links": [ { "type": "terms_of_use", "value": "https://postalform.com/terms" }, { "type": "privacy_policy", "value": "https://postalform.com/privacy" } ], "payment_mode": "test" } } }

First call for an MPP/Link payment challenge:

{ "name": "postalform.create_machine_order", "arguments": { "payment_protocol": "mpp", "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "letter": { "title": "Payment demand letter", "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n" }, "sender_name": "Sender Example", "sender_address_type": "Manual", "sender_address_manual": { "line1": "123 Sender St", "city": "Springfield", "state": "IL", "zip": "62701" }, "recipient_name": "Recipient Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "city": "Springfield", "state": "IL", "zip": "62701" } } }

{ "structuredContent": { "view": "machine_order", "protocol": "mpp", "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "status": "payment_required", "payment": { "www_authenticate": ["Payment ..."], "retry_header": "Authorization", "retry_header_value": "Payment ..." } } }

After Link CLI or Link MCP returns the paid MPP credential, retry the same arguments with:

{ "payment_authorization": "Payment ..." }

For x402, setpayment_protocoltox402; the first response containspayment.payment_required_header, and the retry usespayment_signature.

{ "name": "complete_checkout", "arguments": { "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "payment_data": { "token": "spt_test_123", "provider": "stripe" } } }

{ "structuredContent": { "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "status": "completed", "currency": "usd", "line_items": [ { "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "item": { "id": "postalform_mail_pdf", "quantity": 1 }, "base_amount": 299, "discount": 0, "subtotal": 299, "tax": 0, "total": 299 } ], "fulfillment_options": [ { "type": "shipping", "id": "postalform_standard", "title": "First Class mail", "subtitle": "Mailed via postal carrier", "carrier": "Postal carrier", "carrier_info": "PostalForm print-and-mail provider", "earliest_delivery_time": "2026-07-01T00:00:00.000Z", "latest_delivery_time": "2026-07-06T00:00:00.000Z", "subtotal": 0, "tax": 0, "total": 0 } ], "fulfillment_option_id": "postalform_standard", "totals": [ { "type": "items_base_amount", "display_text": "Items", "amount": 299 }, { "type": "subtotal", "display_text": "Subtotal", "amount": 299 }, { "type": "tax", "display_text": "Tax", "amount": 0 }, { "type": "total", "display_text": "Total", "amount": 299 } ], "order": { "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "permalink_url": "https://postalform.com/order/complete?order_id=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b" }, "messages": [], "links": [ { "type": "terms_of_use", "value": "https://postalform.com/terms" }, { "type": "privacy_policy", "value": "https://postalform.com/privacy" } ] } }

{ "structuredContent": { "view": "order_status", "found": true, "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "is_paid": true, "current_step": "letter_created" } }

{ "isError": true, "content": [ { "type": "text", "text": "recipient_address_manual is required when recipient_address_type is Manual." } ] }

- Idempotency: userequest_idon draft creation tools (postalform.create_order_draft,postalform.create_letter_order_draft,postalform.create_form_order_draft) and onpostalform.create_machine_order. Reuse the same value and same order fields on retries. The server will return the existing draft/order.
- Errors: tool calls that fail validation returnisError=truewith a human-readable message. For Instant Checkout,complete_checkoutcan also return ACP messages with error codes likepayment_declinedorrequires_3ds.
- Instant Checkout fallback: ifwindow.openai.requestCheckoutis unavailable orcheckout_session.payment_providerlacksmerchant_id, usecheckout_urlinstead.
- Order status steps:payment_received,receiver_address_verified,sender_address_verified,pdf_normalized,letter_created,email_sent,canceled,refunded,abandoned.

- All orders are printed from PDFs. Forpostalform.create_order_draftyou supply the PDF. Forpostalform.create_letter_order_draftandpostalform.create_form_order_draftPostalForm generates the PDF server-side. PDFs are sanitized before printing.
- Inlineform.attachmentsare base64 JSON and may total at most 12 MB after decoding. Follow each attachment'sallowed_types,max_files, and machine-cappedmax_size_mbvalues from the workflow schema.
- For a workflow withrecipient.mode="user", the top-level recipient name/address controls the envelope. Keep it aligned with recipient address-role fields inform.fields; those fields do not override the top-level machine-order address.
- Max 199 pages and 100 MB per file.
- download_urlmust be HTTPS and hosted on an allowlisted domain (ChatGPT attachments useoaiusercontent.comby default). The URL must be publicly reachable without auth headers. If you cannot provide an allowlisted URL, usepostalform.create_pdf_uploadto get anupload_token, or pass adata:application/pdf;base64,...URL instead.
- Address countries default toUSwhen omitted. Use Loqate address ids returned bypostalform.search_addresses(the id prefix carries the country), or use manual address input with_address_type="Manual"and_address_manual.countryCode. Machine orders enforce the same country list as the checkout address picker:US,CA,AT,BE,CH,DE,ES,FR,GB,IN,LU, andNL; unsupported or invalid codes are rejected. Bulk CSVs accept the same list throughcountry,country_code, orcountrycode.
- Address suggestions can includetype="Container"(buildings/complexes). Callpostalform.search_addressesagain withcontainer=<id>and a refined query (suite, unit, PO Box) to gettype="Address"results. Onlytype="Address"(not Container) is valid for Loqate-based order drafts.

MCP safety, permissions, and rate limits

Treat PostalForm as a real-world action tool because it can create mail drafts and, in machine-payment flows, place paid mail orders after an owner-approved payment challenge. In chat clients, configure the server withrequire_approval: "always"and require human review before sending user documents, addresses, or payment credentials.

Draft-creating tools and direct machine-order tools are also limited by unpaid-order throttling. The default unpaid-order creation limit is 10 attempts per hour per client IP. On rate limits, MCP tools return an error response and HTTP wrapper calls may return429.

Security scanners should treat hosted checkout as the default safe path: the tool can create a draft, but the customer still reviews the PDF, addresses, price, and mailing options before payment. Direct machine payment should stay behind explicit owner approval, spending limits, idempotentrequest_idvalues, and a preview review step whenpreview_urlis present.

- OpenAI remote MCP and connectors
- Model Context Protocol documentation
- Google Gemini MCP tools
- Stripe Machine Payments Protocol
- x402 payment protocol

- Is PostalForm a mail API?Yes. PostalForm exposes machine-order REST endpoints, an OpenAPI catalog, and a remote MCP server for creating physical-mail drafts, quotes, machine-payment orders, and fulfillment-status lookups.
- Can an MCP server send real postal mail?Yes, but PostalForm separates draft creation from paid mailing. Draft tools create an unpaid hosted-checkout draft; direct machine-order tools should be used only by authorized runtimes with spending controls and approval.
- What is the safest default for ChatGPT, Claude, Gemini, Cursor, or Codex?Use the remote MCP endpoint at[https://postalform.com/mcp, configure approval for mail side effects, create a hosted-checkout draft, and let the user review the PDF, addresses, price, and options before payment.
- Can an agent pay for mail with x402 or MPP?Yes. PostalForm supports direct machine-payment flows for authorized autonomous runtimes. The unpaid call returns a payment challenge, and the paid retry must include the x402 payment signature or MPP authorization.
- Do I need a PostalForm API key?Not for the current public MCP endpoint or machine-payment flow. Some high-volume, abuse-sensitive, or allowlisted deployments may require coordination withsupport@postalform.com.
- Can I upload PDFs through the API or MCP?Yes. Use the PDF upload tool to create a short-lived upload token, pass an allowlisted HTTPS download URL, use a ChatGPT attachment URL, or provide a data URL where supported.
- How do I keep mail side effects safe?Treat physical mail as a real-world action. Use hosted checkout by default, require human approval, set spend limits, reuse idempotency request IDs, and review preview URLs before payment when present.

Generate documents, process PDFs, and manage e-signature workflows using the PDFGate API.

…