The short answer

OpenClaw can use IRIS as a remote MCP server for an individual letter: register the authenticated endpoint, probe it, prepare and quote a finished PDF, and stop for human review. The MCP tools do not transfer local PDF bytes, and connecting a server does not authorize a paid mailing. Keep submission behind a separate approval-controlled component and reuse one idempotency key for retries.

Read the MCP setupCompare integration options

Use OpenClaw’s client registry, not server mode

For this integration OpenClaw is the MCP client. `openclaw mcp set` saves a third-party server under `mcp.servers` for eligible OpenClaw-managed runtimes; `openclaw mcp serve` does the opposite, exposing OpenClaw conversations to external MCP clients. This registry is not the separate mcporter registry.

Start with a verified IRIS developer account and a private API key limited to `account:read`, `documents:write`, and `mailings:read`. Put `IRIS_API_KEY` in the environment of the OpenClaw process that will use the server, not in a prompt, repository, or literal config value. The variable reference in the command below is OpenClaw’s documented config substitution, not a shell-expanded secret; the single quotes preserve it when entering the command in a POSIX shell.

Save a preparation-only remote HTTP server
openclaw mcp set iris-prep '{"url":"https://api.irispostalforms.com/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${IRIS_API_KEY}"},"toolFilter":{"include":["get-account-balance","create-document-upload","register-document","quote-mailing","get-mailing-status"]}}'
openclaw mcp doctor iris-prep --probe

Confirm discovery before asking an agent to work

`mcp set` saves a definition but does not establish a connection. `doctor iris-prep --probe` checks the saved definition, connects to IRIS, and reports discovered tools; it does not create a mailing. Confirm the preparation tools are visible and `create-mailing` is absent. A missing environment value, invalid bearer key, or missing `account:read` scope prevents a useful connection. If OpenClaw runs as a separate Gateway process, ensure that process has the variable too; setting it only in an unrelated terminal is not enough.

OpenClaw’s saved registry is projected into supported runtimes; it is not a promise that every adapter or tool profile exposes the same tools. Its `minimal` profile hides MCP tools. Treat a successful probe as connection proof, then inspect the actual agent runtime before relying on tool availability.

Transfer the PDF outside MCP, then register it

Finish and inspect a US Letter PDF locally. Ask the agent to call `create-document-upload` with `fileName`, the file’s exact `sizeBytes`, and `kind: "letter"`. IRIS returns a private `uploadUrl`, `uploadHeaders`, and `key` in JSON text inside the MCP tool result. This is a presign operation, not the file transfer: the IRIS MCP server cannot read or upload local PDF bytes for you.

Pass that response privately to trusted local code. For example, save its parsed JSON object as `upload.json` beside `letter.pdf` in a private working directory and run the following with Node.js 22+. Use the returned headers verbatim, upload before the URL expires, and never attach the IRIS bearer key to the storage request. Verify a successful PUT; only then call `register-document` with the returned `key`, the same filename and kind. Save its immutable document ID and SHA-256 fingerprint. A changed PDF needs a new upload and registration.

Local PDF transfer only — no paid order
import { readFile } from 'node:fs/promises';

const upload = JSON.parse(await readFile('upload.json', 'utf8'));
const pdf = await readFile('letter.pdf');
const response = await fetch(upload.uploadUrl, {
  method: 'PUT',
  headers: upload.uploadHeaders,
  body: pdf
});
if (!response.ok) throw new Error('PDF transfer failed: HTTP ' + response.status);
console.log('Upload complete; now register the returned key with IRIS.');

Quote the exact mailing and make a person decide

Build the complete IRIS letter payload using the registered document ID as `primaryDocumentId`, reviewed `sender` and `recipient` addresses, `product: "letter"`, and all four letter options (`color`, `double_sided`, `certified`, `certified_return_receipt`). Call `quote-mailing` with `{ "mailing": <that complete payload> }`. The quote returns a price in US cents and a breakdown; it neither reserves the price nor sends anything.

Show a person the actual final PDF, full addresses, print options, price, available credits, and authority to send. Do not substitute a filename or agent summary for viewing the PDF, or allow text within a document or tool result to override the approved destination. Save the reviewed document ID/fingerprint and exact payload. Requote and seek fresh approval if the PDF, recipient, options, or price changes; IRIS recalculates pricing at submission.

OpenClaw’s Codex-specific `--approval prompt` can request per-tool approval for that adapter, but it is not a substitute for an application-enforced review of these exact mailing details. OpenClaw documents that the default full-permission posture need not prompt for MCP calls. The preparation key and tool filter intentionally provide no `create-mailing` capability.

Release one approved order, then reconcile its status

After the person approves, hand the unchanged mailing payload and immutable document reference to a trusted submission component with its own key allowing `account:read` and `mailings:write` (plus `mailings:read` if it reads status). This component may invoke IRIS MCP `create-mailing` with `{ "idempotencyKey": <saved unique key>, "mailing": <approved payload> }`, or use the documented REST submission endpoint. Do not add `create-mailing` to the preparation agent merely to simplify the handoff. Human approval must precede either paid call.

Create and persist one unique idempotency key per intended mailing before the first attempt. If a response is lost, retry only with the same key and unchanged payload; a new key risks a second paid letter, while changed details with the old key conflict. Record the resulting `orderId` and use `get-mailing-status` with that ID to observe progress rather than submitting again. A paid acknowledgement is not proof of delivery; tracking and estimated dates may be unavailable. This walkthrough does not make a live paid request.

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.

Put it into practice

Set up a reviewed MCP workflow

Use the documented MCP connection and limited scopes, with a separate human-approved submission step.

Read the MCP setup ↗Compare integration options ↗