The short answer
Claude Code can work with the IRIS server through Streamable HTTP MCP and a bearer API key. Use it to prepare a document and obtain a quote, then review the exact PDF and mailing details before authorizing create-mailing. The MCP server does not upload local PDF bytes by itself.
Prepare the account and local document
Start with a verified IRIS developer account and a final US Letter PDF that your business is authorized to mail. For preparation, use a key with account:read, documents:write, and mailings:read scopes. Submission additionally requires mailings:write and sufficient credits. Leaving the write scope out of a preparation-only key gives you a concrete boundary around what that key can do.
This walkthrough is for Claude Code, where a local tool can read a PDF and transfer its bytes. A Claude web or desktop connector may expose a different authentication or file-access flow. Do not assume an integration is installed merely because a chat can draft a letter.
Connect the authenticated MCP endpoint
Anthropic documents HTTP MCP connections and environment-variable expansion in .mcp.json. Merge the following entry into your project configuration, and supply IRIS_API_KEY to the environment that launches Claude Code. The file contains a variable reference, not your real credential. Review the server configuration when Claude asks to trust it.
Open /mcp in Claude Code to inspect the connection. A missing environment value, revoked key, or missing account:read scope will prevent a useful session. Keep actual credentials out of prompts, screenshots, source control, and shared logs.
{
"mcpServers": {
"iris": {
"type": "http",
"url": "https://api.irispostalforms.com/mcp",
"headers": {
"Authorization": "Bearer ${IRIS_API_KEY}"
}
}
}
}Use the tools in the right order
IRIS exposes six server tools. A local file upload is a separate operation between the second and third tools below: your trusted local code must PUT the actual bytes to the returned storage URL, using uploadHeaders. Returning an upload URL is not evidence that the file arrived.
| Tool | Purpose |
|---|---|
| get-account-balance | Read the account’s available prepaid credits. |
| create-document-upload | Request a temporary private PDF upload URL. |
| register-document | Validate the uploaded file and receive its immutable document ID. |
| quote-mailing | Calculate a price for the complete mailing object. |
| create-mailing | Create one paid mailing after review; requires idempotencyKey and mailing. |
| get-mailing-status | Read the resulting order using orderId. |
Give Claude a preparation task with a clear stopping point
The following is an example instruction for a document you have already approved for processing. Replace the filename and supply the real addresses through your trusted workflow. It deliberately stops before an order is created.
Prepare letter.pdf for one IRIS mailing.
Use the sender and recipient I supplied; do not infer addresses.
Upload the PDF privately and register the exact file.
Quote a black-and-white, double-sided letter.
Show me the document ID, PDF, addresses, options, and price.
Stop before create-mailing. Ask me to review the complete mailing.Approve the document, then keep the receipt
Open the actual PDF and check every page. Confirm that the recipient is current, the contents are accurate, and the price and mailing option fit the job. If Claude revises the document after review, register the new PDF and review again. Approval of an earlier draft should not carry over to a changed file.
For submission, persist one idempotencyKey with the approved mailing. Save the returned orderId immediately. If the response is lost, retry the same intent with the same key and payload; creating a fresh key can create another paid letter. A paid response means an order exists, not that USPS has delivered it. Use get-mailing-status for the next operational step.
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.
Published by IRIS Postal Forms, operated by Great Lakes Computing Office LLC. Send a correction.