ONCE

npx add-mcp 'https://once.aiagenthuddle.com/mcp'

Qué hace

Registra las acciones de proveedores compatibles bajo una clave de operación estable. Las solicitudes repetidas reutilizan la operación; un resultado incierto permanece incierto hasta que la evidencia lo resuelva.

Beta pública para desarrolladores: documentación, registro y uso gratuito disponibles. Usa tu clave de API del producto para las solicitudes; los ejemplos públicos no requieren acceso de vista previa de Vercel. Hay suscripciones de pago disponibles; el uso gratuito sigue disponible.

Empieza aquí: un ejemplo funcional

1. Crea una cuenta, confirma tu correo electrónico y luego crea tu proyecto ONCE. El acceso gratuito es suficiente; no se necesita suscripción para este ejemplo.
2. Guarda la clave de API mientras esté visible. Mantenla en la configuración del lado del servidor.
3. Usa Node.js 22 o superior. Descarga el ejemplo independiente y crea un archivo privado .env junto a él.

También necesitas una clave secreta de sandbox de Stripe que comience con sk_test_ con permiso para crear PaymentIntents. Una clave publicable no funcionará. El ejemplo crea un objeto de prueba no confirmado; no cobra una tarjeta. ONCE recibe esta credencial para la solicitud y no la almacena en el libro mayor.

ONCE_API_KEY=replace_with_your_project_key
STRIPE_TEST_KEY=replace_with_your_Stripe_sandbox_secret_key
ONCE_OPERATION_KEY=quickstart-intent-001

Agrega .env a .gitignore. Nunca lo confirmes en el repositorio, lo pongas en un paquete de navegador ni pegues credenciales en mensajes de soporte. Mantén la misma ONCE_OPERATION_KEY para las reejecuciones de este ejemplo; cambiarla crea una nueva operación lógica.

node --env-file=.env once-first-operation.mjs

Cómo se ve el éxito

El script registra un PaymentIntent de prueba de Stripe no confirmado, repite la misma solicitud lógica y verifica que el ID de operación siga siendo el mismo. Luego lee el libro mayor. Un estado COMMITTED registra el éxito del proveedor; UNKNOWN o AMBIGUOUS significa detenerse e inspeccionar. Nunca llama a retry.

La salida esperada incluye PASS:. Lee también los mensajes de estado adjuntos: una reproducción exitosa por sí sola no prueba un efecto del proveedor. El ejemplo realiza solicitudes reales a la API y usa una pequeña cantidad de tus unidades de solicitud.

¿Algo falló? Revisa la tabla de configuración a continuación antes de cambiar una clave o repetir una acción incierta.

Tu conexión con GitHub

Usa un token de grano fino limitado a tu repositorio con permisos de lectura/escritura de Issues. Proporciona Once-GitHub-Token y Once-GitHub-Repository: owner/repository en los encabezados de la solicitud. El repositorio permanece vinculado a la operación. Reintentar o reconciliar requiere tu credencial; un token nuevo puede reemplazar a uno caducado pero no puede redirigir la operación. Los tokens nunca se almacenan en el libro mayor. Crear un issue es una escritura real en el repositorio.

El SDK acepta estas credenciales como su tercer argumento del constructor: {githubToken, githubRepository}. Los transportes MCP envían los mismos encabezados HTTP; las credenciales nunca son argumentos de herramientas. La consulta de solo lectura necesita solo tu clave de ONCE.

Endpoints REST

Endpoint	Comportamiento
POST /v1/operations	Crea o recupera una operación lógica usando Idempotency-Key.
GET /v1/operations/{id}	Lee el estado duradero y la seguridad de reintento.
POST /v1/operations/{id}/reconcile	Lee la evidencia del proveedor y actualiza la operación.
POST /v1/operations/{id}/retry	Reintenta solo cuando la evidencia registrada lo permita.

Comportamiento ante fallos y límites

• Reutilizar una clave con parámetros diferentes devuelve un conflicto sin otra acción del proveedor.
• Los estados UNKNOWN y AMBIGUOUS nunca permiten reenvío a ciegas. Un objeto de proveedor ausente por sí solo no prueba la no confirmación.
• Los adaptadores compatibles crean PaymentIntents de prueba de Stripe no confirmados en tu sandbox e issues de GitHub en un repositorio vinculado usando tu credencial de ámbito de solicitud. No capturan pagos en vivo ni ofrecen acceso HTTP arbitrario.
• La idempotencia nativa del proveedor puede ser suficiente para una integración única. ONCE agrega un registro de operación duradero y estados explícitos de resultado/recuperación para las acciones compatibles. No promete efectos universales de exactamente una vez.

Los cuerpos de solicitud están limitados a 16 KiB. Las claves faltantes, revocadas o de productos cruzados son rechazadas. Los límites de velocidad devuelven HTTP 429; la indisponibilidad del servicio sigue siendo un error en lugar de una operación exitosa.

Ejemplos ejecutables y lista de verificación de integración

Descarga once-first-operation.mjs · Lee el código fuente del ejemplo público. No se requiere dependencia npm ni plan de pago.

Cuándo esta herramienta ayuda

Usa ONCE cuando tu aplicación necesite un registro duradero de acciones de proveedores compatibles y decisiones explícitas de recuperación después de un tiempo de espera o un bloqueo. La idempotencia nativa del proveedor puede ser suficiente para una integración única y sencilla; ONCE agrega un ID de operación consultable, estado registrado y reconciliación basada en evidencia. No hace que acciones arbitrarias sean exactamente una vez.

Antes de ponerlo en un worker

• Persiste tu clave de operación lógica antes del envío y reutilízala con parámetros idénticos.
• Guarda el ID de operación devuelto para que otro proceso pueda inspeccionar el mismo registro del libro mayor.
• Trata UNKNOWN y AMBIGUOUS como no resueltos; reconcilia con evidencia antes de considerar un reintento.
• Maneja HTTP 429 y fallos temporales con retroceso limitado. No conviertas los reintentos en un bucle infinito.

Problemas de configuración

Lo que ves	Qué verificar
HTTP 401	Usa la clave de API del proyecto de este producto en Authorization: Bearer. Una clave de Supabase, una clave de Stripe o la clave del otro producto no autenticarán. Las claves reemplazadas dejan de funcionar inmediatamente.
HTTP 400	Verifica nombres de campos, tipos y valores requeridos contra el ejemplo. Las credenciales de Stripe deben ser claves de prueba secretas; las credenciales en vivo no se aceptan.
HTTP 409	Parámetros diferentes con una clave lógica existente entran en conflicto. Restaura los parámetros originales; nunca cambies claves solo para evitar un resultado incierto.
HTTP 429	Verifica el uso mensual y los límites de velocidad. Espera antes de otro intento. La reconciliación de ONCE tiene una reserva mensual separada de 100 solicitudes; un error de cuota nunca prueba un reintento seguro.
Tiempo de espera o ejemplo interrumpido	Conserva la clave lógica. Vuelve a ejecutar con los mismos parámetros para recuperar esa operación; no llames a retry a ciegas.

Para soporte, envía el nombre del producto, un error/estado redactado, el ID de operación o arrendamiento y la marca de tiempo UTC a accounts@aiagenthuddle.com. Nunca envíes claves de API, tokens de proveedor, contraseñas ni enlaces de inicio de sesión.

Notas de ingeniería

Un tiempo de espera no te dice si ocurrió una acción: un escenario de fallo concreto y los límites del mecanismo de recuperación.

Acceso MCP y SDK

Conecta un cliente MCP

Elige un servidor remoto usando Streamable HTTP. Usa los siguientes detalles de conexión en un cliente que admita encabezados bearer:

URL del servidor	https://once.aiagenthuddle.com/mcp
Encabezado	Authorization: Bearer YOUR_ONCE_API_KEY
Herramientas esperadas	once_create, once_get, once_retry, once_reconcile

Usa la configuración de credenciales privadas de tu cliente. Un cliente que solo admite OAuth no puede autenticarse en este endpoint de clave de API. Si el descubrimiento devuelve 401, verifica el encabezado antes de invocar herramientas. Las credenciales del proveedor deben usar los encabezados HTTP dedicados descritos anteriormente, nunca argumentos de herramientas. Comienza con el descubrimiento; crear un issue escribe en tu repositorio.

JavaScript · Node.js

Guarda el módulo como sdk.js en un proyecto con "type": "module". El cliente usa la API fetch integrada.

import { OnceClient } from './sdk.js';

const once = new OnceClient(
  'https://once.aiagenthuddle.com',
  process.env.ONCE_API_KEY,
  { stripeTestKey: process.env.STRIPE_TEST_KEY }
);

const operation = await once.create(
  'order-123-intent', 'stripe', 'create_payment_intent',
  { amount: 100, currency: 'gbp' }
);
// Preserve the operation ID. Inspect before any retry.
console.log(operation);

MCP sin estado autenticado está disponible en /mcp. Herramientas: once_create, once_get, once_retry, once_reconcile. Los clientes oficiales actuales y heredados han pasado verificaciones protegidas alojadas. No se anuncian sesiones SSE reanudables ni funciones MCP no compatibles.

El cliente JavaScript independiente está disponible directamente. Descarga sdk.js en tu proyecto del lado del servidor. No se publica ningún paquete npm. Mantén las credenciales fuera de los paquetes de navegador.