The short answer
IRIS provides an authenticated MCP server for individual US physical mailings at https://api.irispostalforms.com/mcp. Use a client that supports remote Streamable HTTP and bearer headers, initialize the connection, and discover its tools. The server can prepare an upload, register a PDF, quote a mailing, submit a reviewed paid order, and read status; your trusted code must separately transfer the PDF bytes and enforce human approval before submission.
Check the endpoint, transport, and client before connecting
A physical-mail MCP server is not a chat feature that automatically sends a letter. It is a tool endpoint a compatible client can call on your account’s behalf. Use the IRIS documentation as the source of truth for the server URL: https://api.irispostalforms.com/mcp. Do not substitute the REST API origin, a consumer website URL, or an unverified directory listing for this endpoint.
Your client must support authenticated remote Streamable HTTP, send an IRIS API key as Authorization: Bearer, and negotiate the MCP connection. Streamable HTTP requests advertise application/json and text/event-stream in Accept. Follow your particular client’s documented way to supply the URL and secret; configuration syntax and support for custom headers vary. Initialize the connection and use MCP tool discovery to see the available tools rather than assuming a pasted prompt or a local stdio connector has established access.
Tool results contain JSON serialized in MCP text content; they are not the REST API’s data response envelope. A connected client also needs a trusted way to access and transfer the final PDF, because the remote MCP server cannot read an arbitrary file on your computer.
Discover six tools and separate preparation from spending
Every IRIS MCP request requires account:read. A preparation credential can add documents:write to request and register an upload, and mailings:read to quote and check status. Only the component allowed to submit an approved paid mailing needs mailings:write. A client that exposes every tool through a broad key makes a mistaken or manipulated call more consequential; a preparation-only key cannot create a mailing.
Use the discovered input schemas rather than guessing field names. The quote and submit tools take a complete mailing object with a registered document ID, complete sender and recipient addresses, and the applicable print options. create-mailing also requires an idempotencyKey. Keep API keys in trusted secret storage, not in a shared prompt, browser bundle, PDF, screenshot, or repository.
| Tool | Purpose | Additional scope |
|---|---|---|
| get-account-balance | Read available prepaid credits. | None |
| create-document-upload | Request a private, temporary PDF upload URL. | documents:write |
| register-document | Validate the transferred PDF and obtain its immutable document ID. | documents:write |
| quote-mailing | Calculate the price for a complete mailing object. | mailings:read |
| create-mailing | Create one paid order after review. | mailings:write |
| get-mailing-status | Read the current state of an existing order. | mailings:read |
Transfer PDF bytes through the trusted upload path
The create-document-upload tool returns a temporary uploadUrl, uploadHeaders, and a storage key. That tool does not itself upload the PDF. In your trusted local or server-side code, PUT the exact bytes of the approved PDF to that URL before calling register-document with the returned key, fileName, and kind. Send every returned uploadHeaders value, including If-None-Match when supplied; do not send the IRIS bearer key to the storage URL. Check that the PUT succeeded, then register the document and retain its document ID and fingerprint. The storage key is not a document ID, and a presigned URL is not proof of a completed upload.
Treat both the PDF and presigned URL as sensitive. Limit who can see the URL, use it within its expiry, and do not ask an untrusted model tool to fetch arbitrary returned URLs with your credentials. A changed PDF requires a new upload, registration, and review; approval of the old document does not authorize a revised one. Check the documented PDF size, page, and dimension limits before building a workflow around a particular mail piece.
Put a review boundary between a quote and a paid order
Call quote-mailing with the registered document ID, sender, recipient, and mailing options. A quote calculates a price; it does not reserve that price, spend credits, or mail anything. Show a person the actual final PDF, both complete addresses, print options, current quote, purpose, and authority to send. If the document or payload changes, quote and review again. Submission recalculates pricing, so refresh a stale quote and return a changed amount to the reviewer rather than treating an earlier estimate as guaranteed.
Only after that review should trusted application logic allow create-mailing with the approved mailing object and one durable idempotencyKey for that intended letter. Persist the key and payload before the first attempt and save the returned orderId. If a response is lost, retry the same key with the unchanged payload; a new key can create another paid letter, while changing the payload under the old key conflicts. A paid acknowledgment means an order exists, not that it has entered production or reached the recipient. Use get-mailing-status with orderId for follow-up; tracking and estimated dates can be absent, and delivery is not guaranteed.
A client-neutral connection and safety checklist
Before treating a listed MCP server as suitable for physical mail, verify its operator, transport, authentication, tools, spending permissions, and document-transfer path. Client-specific setup belongs in that client’s own documentation; the checklist below applies whether your client is a coding assistant or a custom application.
Do not let instructions inside a PDF, retrieved page, or tool response change the approved destination or authorize submission. A tool description saying a human should review is useful guidance, not an enforcement mechanism. Place the approval gate in trusted code or an equivalent controlled process, and reconcile uncertain order outcomes instead of automatically sending a replacement.
- Verify the official endpoint is https://api.irispostalforms.com/mcp and the client supports authenticated remote Streamable HTTP with bearer headers.
- Create a scoped key for the stage you are implementing; keep mailings:write out of a preparation-only connection and never expose the key to untrusted content.
- Initialize MCP and discover the actual tools and schemas. Confirm the preparation tools are accessible before building a mailing.
- Prepare the final PDF in a trusted environment; request an upload URL, PUT bytes with all returned upload headers, check success, then register and save the document ID.
- Quote the exact mailing and show the real PDF, addresses, options, price, and intent to an authorized person; stop if anything changes or cannot be verified.
- Submit only the approved payload with a saved idempotency key through a permitted path; preserve the order ID, retry uncertain results with the same key and payload, and read status rather than placing another order.
Sources & further reading
Product details checked against the IRIS API contract when this article was published. Platform references can change; consult the linked documentation when implementing.
- IRIS API documentation: MCP, uploads, review, and status
- Model Context Protocol: Streamable HTTP transport
Published by IRIS Postal Forms, operated by Great Lakes Computing Office LLC. Send a correction.