CLAIM

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

Qué hace

Adquiere un bloqueo exclusivo o un semáforo con capacidad limitada, renueva antes de que expire y libera cuando termines. Los tokens de fencing incrementales ayudan a los consumidores cooperativos a rechazar trabajadores obsoletos.

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 CLAIM. 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.

CLAIM_API_KEY=replace_with_your_project_key

Agrega .env a .gitignore. Nunca lo confirmes en el repositorio, lo pongas en un paquete de navegador ni pegues credenciales en mensajes de soporte.

node --env-file=.env claim-contention.mjs

Cómo se ve el éxito

El script verifica GRANTED → DENIED mientras se mantiene un bloqueo, luego RELEASED → GRANTED con un token de fencing más alto. Libera todas las concesiones conocidas en un bloque finally. Esta es una demostración de un solo proceso, no evidencia de agentes independientes ni protección de una escritura real posterior.

La salida esperada incluye PASS:. Lee también los mensajes de estado adjuntos: los trabajadores y el almacenamiento posterior deben hacer cumplir la propiedad y el fencing. 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.

Endpoints REST

Endpoint	Comportamiento
POST /v1/leases	Adquiere propiedad. HTTP 200 GRANTED o 409 DENIED.
POST /v1/leases/{id}/renew	Renueva un bloqueo no expirado; la autoridad expirada no puede regresar.
DELETE /v1/leases/{id}	Libera un bloqueo activo. NOT_ACTIVE es un resultado terminal seguro.
GET /v1/resources/{resource}/status	Observa capacidad y disponibilidad dentro de tu proyecto.
POST /v1/resources/{resource}/wait	Espera disponibilidad, limitada a un máximo de 20 segundos. La adquisición sigue siendo competitiva.

Comportamiento ante fallos y límites

• Los tokens de fencing son cadenas decimales. Compáralos como enteros y hazlos cumplir en el sistema posterior que confirma el efecto. Un bloqueo no puede detener por sí solo a un trabajador expirado.
• Usa un request_id estable al reintentar la misma solicitud de adquirir, renovar o liberar. Sin él, otra adquisición es una operación nueva. Una reproducción no puede revivir un bloqueo expirado.
• Los recibos de liberación exitosos reproducen su resultado original. Una liberación nueva que devuelve NOT_ACTIVE no almacena ni reserva su ID de solicitud, por lo que una entrada diferente que use ese ID no registrado puede tratarse como una solicitud nueva. Usa IDs distintos para solicitudes distintas. Los recibos almacenados rechazan la reutilización con entrada diferente.
• Los recursos están aislados por proyecto. El modo predeterminado es exclusivo; el modo semáforo requiere una capacidad explícita.
• La vista previa alojada superó una ráfaga exclusiva de 1,000 solicitudes y una ráfaga de capacidad cinco después de reparar los fallos de límite de conexión. Esto es evidencia de corrección bajo esas condiciones, no un SLA de rendimiento ilimitado.

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

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

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

Cuándo ayuda esta herramienta

Usa CLAIM cuando trabajadores que se ejecutan de forma independiente necesiten propiedad temporal compartida o un número limitado de titulares concurrentes. Si tu base de datos existente ya proporciona coordinación adecuada, otro servicio puede ser innecesario. CLAIM expone la propiedad a través de HTTP/MCP; las escrituras posteriores seguras aún requieren cumplimiento atómico de fencing.

Antes de ponerlo en un trabajador

• Mantén el mismo ID de solicitud al reintentar una solicitud incierta; una solicitud diferente necesita un ID diferente.
• Renueva antes de la expiración, detén el trabajo cuando se pierda la autoridad y libera en la limpieza.
• Compara los tokens de fencing como enteros. Compara y confirma atómicamente en el sistema de almacenamiento posterior; una verificación en memoria es insuficiente.
• 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, Stripe o la clave del otro producto no autenticará. Las claves reemplazadas dejan de funcionar inmediatamente.
HTTP 400	Verifica nombres de campos, tipos y valores requeridos contra el ejemplo. TTL es un entero de 5 a 86,400 segundos; los IDs de solicitud deben ser UUID.
HTTP 409	DENIED es contención normal: otro titular posee la capacidad. Espera con retroceso limitado; no comiences trabajo sin GRANTED.
HTTP 429	Verifica el uso mensual y los límites de velocidad. Espera antes de otro intento; nunca evites una denegación comenzando trabajo.
Tiempo de espera agotado o ejemplo interrumpido	Detén el trabajo. Las concesiones desconocidas expiran después del TTL de 60 segundos del ejemplo. En tu integración, conserva los IDs de solicitud para recuperar adquisiciones inciertas.

Para soporte, envía el nombre del producto, un error/estado redactado, el ID de operación o bloqueo 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 bloqueo expirado no puede detener a un trabajador: 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 de portador:

URL del servidor	https://claim.aiagenthuddle.com/mcp
Encabezado	Authorization: Bearer YOUR_CLAIM_API_KEY
Herramientas esperadas	claim_acquire, claim_renew, claim_release, claim_status, claim_wait

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.

JavaScript · Node.js

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

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

const claim = new ClaimClient(
  'https://claim.aiagenthuddle.com',
  process.env.CLAIM_API_KEY
);

const result = await claim.acquire({
  resource: 'job/123', agent_id: 'worker-a',
  ttl_seconds: 30, request_id: crypto.randomUUID()
});
// Inspect GRANTED / DENIED before starting work.
// Enforce the granted fencing token downstream.
console.log(result);

MCP sin estado autenticado está disponible en /mcp. Herramientas: claim_acquire, claim_renew, claim_release, claim_status, claim_wait. Los clientes oficiales actuales y heredados han superado verificaciones alojadas protegidas. 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.