Prepara una carta y calcula su presupuesto con OpenClaw y el MCP de IRIS

Usa el registro de clientes de OpenClaw, no el modo servidor

En esta integración, OpenClaw es el cliente MCP. `openclaw mcp set` guarda un servidor de terceros en `mcp.servers` para los entornos de ejecución compatibles administrados por OpenClaw; `openclaw mcp serve` hace lo contrario: expone las conversaciones de OpenClaw a clientes MCP externos. Este registro no es el registro independiente de mcporter.

Comienza con una cuenta de desarrollador de IRIS verificada con créditos prepagados y una clave de API privada limitada a `account:read`, `documents:write` y `mailings:read`. Coloca `IRIS_API_KEY` en el entorno del proceso de OpenClaw que usará el servidor, no en un prompt, repositorio ni valor literal de configuración. La referencia a la variable en el siguiente comando es la sustitución de configuración documentada de OpenClaw, no un secreto expandido por el shell; las comillas simples la preservan al introducir el comando en un shell POSIX.

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

• Comandos de registro y prueba de conexión MCP de OpenClaw
• Sustitución de variables de entorno de OpenClaw
• Documentación de la API y MCP de IRIS
• Consulta los requisitos comunes de MCP para correo físico

Confirma la detección de herramientas antes de pedirle a un agente que trabaje

`mcp set` guarda una definición, pero no establece una conexión. `doctor iris-prep --probe` comprueba la definición guardada, se conecta a IRIS e informa de las herramientas detectadas; no crea un envío postal. Confirma que las herramientas de preparación estén visibles y que `create-mailing` no aparezca. La ausencia de un valor de entorno, una clave bearer no válida o la falta del alcance `account:read` impiden establecer una conexión útil. Si OpenClaw se ejecuta como un proceso Gateway independiente, asegúrate de que ese proceso también tenga la variable; no basta con establecerla en una terminal ajena al proceso.

El registro guardado de OpenClaw se incorpora a los entornos de ejecución compatibles; eso no garantiza que todos los adaptadores o perfiles de herramientas expongan las mismas herramientas. Su perfil `minimal` oculta las herramientas MCP. Considera una prueba exitosa como evidencia de conexión y luego inspecciona el entorno de ejecución real del agente antes de dar por hecho que las herramientas están disponibles.

Transfiere el PDF fuera de MCP y luego regístralo

Termina e inspecciona localmente un PDF de tamaño carta estadounidense (US Letter). Pídele al agente que llame a `create-document-upload` con `fileName`, el valor exacto de `sizeBytes` del archivo y `kind: "letter"`. IRIS devuelve una `uploadUrl` privada, `uploadHeaders` y `key` como texto JSON dentro del resultado de la herramienta MCP. Esta operación genera una URL prefirmada, no transfiere el archivo: el servidor MCP de IRIS no puede leer ni cargar por ti los bytes de un PDF local.

Pasa esa respuesta de forma privada a un código local de confianza. Por ejemplo, guarda su objeto JSON analizado como `upload.json` junto a `letter.pdf` en un directorio de trabajo privado y ejecuta lo siguiente con Node.js 22+. Usa los encabezados devueltos sin modificarlos, realiza la carga antes de que venza la URL y nunca adjuntes la clave bearer de IRIS a la solicitud de almacenamiento. Verifica que PUT se complete correctamente; solo entonces llama a `register-document` con el valor de `key` devuelto y los mismos valores de nombre de archivo y tipo. Guarda su ID de documento inmutable y su huella SHA-256. Si el PDF cambia, se necesita una nueva carga y un nuevo registro.

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.');

• Requisitos de carga y de documentos de IRIS

Cotiza el envío postal exacto y deja la decisión en manos de una persona

Construye el cuerpo completo de datos de la carta de IRIS usando el ID del documento registrado como `primaryDocumentId`, las direcciones revisadas de `sender` y `recipient`, `product: "letter"` y las cuatro opciones de la carta (`color`, `double_sided`, `certified`, `certified_return_receipt`). Llama a `quote-mailing` con `{ "mailing": <ese cuerpo completo de datos> }`. La cotización devuelve un precio en centavos de dólar estadounidense y un desglose; no reserva el precio ni envía nada.

Muestra a una persona el PDF final real, las direcciones completas, las opciones de impresión, el precio, los créditos disponibles y la autorización para enviar. No sustituyas la visualización del PDF por un nombre de archivo o un resumen del agente, ni permitas que el texto de un documento o del resultado de una herramienta anule el destino aprobado. Guarda el ID y la huella del documento revisado y el cuerpo exacto de datos. Vuelve a cotizar y solicita una nueva aprobación si cambia el PDF, el destinatario, las opciones o el precio; IRIS vuelve a calcular el precio al presentar la solicitud de envío.

La opción `--approval prompt` de OpenClaw, específica de Codex, puede solicitar aprobación por herramienta para ese adaptador, pero no sustituye una revisión de estos detalles exactos del envío postal exigida por la aplicación. OpenClaw documenta que la configuración predeterminada con todos los permisos no necesariamente solicita aprobación para las llamadas MCP. La clave de preparación y el filtro de herramientas no ofrecen la capacidad `create-mailing` de manera intencional.

• Guía de cotización y revisión humana de IRIS
• Comportamiento de aprobación MCP de OpenClaw

Envía un pedido aprobado y luego verifica su estado

Después de que la persona dé su aprobación, entrega el cuerpo de datos del envío postal sin cambios y la referencia inmutable al documento a un componente de envío de confianza con su propia clave que permita `account:read` y `mailings:write` (además de `mailings:read` si consulta el estado). Este componente puede invocar `create-mailing` de MCP de IRIS con `{ "idempotencyKey": <clave única guardada>, "mailing": <cuerpo de datos aprobado> }` o usar el endpoint REST documentado para presentar solicitudes de envío. No agregues `create-mailing` al agente de preparación solo para simplificar la transferencia. La aprobación humana debe preceder a cualquiera de las dos llamadas de pago.

Crea y guarda de forma persistente una clave de idempotencia única por cada envío postal previsto antes del primer intento. Si se pierde una respuesta, vuelve a intentarlo únicamente con la misma clave y el cuerpo de datos sin cambios; una clave nueva implica el riesgo de una segunda carta de pago, mientras que los detalles modificados con la clave anterior generan un conflicto. Registra el `orderId` resultante y usa `get-mailing-status` con ese ID para seguir el progreso y consultar cualquier información de seguimiento disponible. IRIS imprime la carta y la entrega a USPS First-Class Mail; USPS indica un plazo de 1–5 días hábiles una vez que la carta está en el correo.

• Presentación de solicitudes de envío, idempotencia y estado en IRIS
• Evita los envíos postales duplicados