Cycles MCP Server

Autoridad de presupuesto en tiempo de ejecución para agentes de IA: reserva, aplica y rastrea el gasto antes de cada llamada de LLM e invocación de herramienta.

GitHub

Documentación

Cycles MCP Server — Control de ejecución de agentes de IA mediante el Protocolo de Contexto de Modelo

Servidor MCP que otorga a cualquier agente de IA compatible con MCP (Claude Code, Cursor, Windsurf, agentes personalizados) autoridad de presupuesto, acción y auditoría en tiempo de ejecución: aplica límites de costo de LLM, topes de llamadas a herramientas, permisos de acción y registros de auditoría antes de la ejecución, sin cambios en el código del agente. Conéctate mediante MCP y usa las herramientas de presupuesto (cycles_reserve, cycles_commit, cycles_release, cycles_decide) directamente desde el bucle de llamadas a herramientas del agente. Impulsado por Cycles. Consulta Modelo de Seguridad y Límite de Aplicación para saber qué se aplica del lado del servidor frente a lo cooperativo en el bucle del agente.

¿Por qué usar esto?

Los agentes de IA autónomos (Claude, GPT, agentes personalizados) llaman a LLMs, invocan herramientas y acceden a APIs externas, pero no tienen una forma integrada de limitar cuánto gastan. Un solo bucle de agente puede quemar cientos de dólares antes de que alguien lo note. Multiplica eso entre inquilinos y equipos, y el control de costos se convierte en un problema real.

Este servidor MCP le da a cualquier agente compatible con MCP una autoridad de presupuesto en tiempo de ejecución: un conjunto de herramientas para verificar, reservar, gastar y liberar presupuesto antes y después de cada operación costosa. El agente pregunta "¿puedo permitirme esto?" antes de actuar e informa lo que realmente usó después.

Quién necesita esto:

Equipos de plataforma que construyen sistemas de agentes multiinquilino que necesitan límites de gasto por cliente o por espacio de trabajo
Desarrolladores de agentes que quieren que los agentes se autorregulen: degradar a modelos más baratos cuando el presupuesto es bajo, omitir llamadas de herramientas opcionales, reducir reintentos
Empresas que despliegan agentes de IA que necesitan salvaguardas para que un agente descontrolado no pueda agotar un presupuesto

Por qué MCP específicamente:

MCP es el protocolo estándar que los hosts de IA (Claude Desktop, Claude Code, Cursor, Windsurf, agentes personalizados) usan para descubrir y llamar herramientas. Al exponer Cycles como un servidor MCP, cualquier agente compatible con MCP obtiene conciencia de presupuesto como un complemento: solo agrega el servidor a tu configuración. No se requiere integración de SDK en el código del propio agente.

El servidor también incluye prompts integrados para que un asistente de IA pueda ayudarte a diseñar tu estrategia de presupuesto, generar código de integración y diagnosticar excesos de presupuesto, no solo aplicar presupuestos en tiempo de ejecución.

Casos de uso

Agente de codificación con tope de dólares por tarea

Ejecutas un agente de Claude Code que escribe e itera sobre código. Cada tarea no debería costar más de $5. El agente llama a cycles_reserve antes de cada llamada a LLM con una estimación de costo en USD_MICROCENTS. Si la reserva regresa como DENY, el agente se detiene e informa "presupuesto agotado" en lugar de acumular cargos silenciosamente. Cuando la llamada se completa, cycles_commit registra el costo real de tokens para que el total acumulado se mantenga preciso.

SaaS multiinquilino con presupuestos por cliente

Tu plataforma permite a los clientes desplegar asistentes de IA. Cada cliente tiene un presupuesto mensual. El agente llama a cycles_check_balance al inicio de una conversación para ver lo que queda, luego cycles_reserve antes de cada invocación de herramienta (búsqueda web, ejecución de código, llamadas a API). Si el cliente Acme está cerca de su límite, la decisión regresa como ALLOW_WITH_CAPS: el agente automáticamente baja a un modelo más barato y omite herramientas opcionales. Los presupuestos de los clientes están aislados; el uso intensivo de un cliente nunca afecta a otro.

Pipeline multiagente con presupuesto compartido

Tienes un orquestador que se distribuye a agentes especialistas: un investigador, un codificador y un revisor. Los tres se alimentan del mismo presupuesto de flujo de trabajo. Cada agente llama a cycles_reserve antes de su trabajo; el servidor de Cycles rastrea reservas concurrentes para que el total nunca exceda el límite del flujo de trabajo. Si el investigador consume el 80% del presupuesto, la próxima reserva del codificador recibe DENY y el orquestador puede decidir omitir el paso de revisión en lugar de exceder el presupuesto.

Pipeline de datos de larga duración con latidos

Un agente procesa un gran conjunto de datos en fragmentos, cada fragmento toma varios minutos. Llama a cycles_reserve con un TTL de 5 minutos antes de cada fragmento, luego cycles_extend cada 60 segundos para mantener la reserva viva mientras procesa. Si el agente se bloquea, la reserva expira automáticamente y el presupuesto bloqueado regresa al grupo: no se necesita limpieza manual.

Medición de uso de tipo "dispara y olvida"

Tienes un sistema existente que ya hace llamadas a LLM y solo quieres rastrear el gasto, no limitarlo. Después de que cada llamada se completa, el agente dispara cycles_create_event con el costo real. No se necesita reserva: el evento se aplica atómicamente a todos los ámbitos de presupuesto (inquilino, espacio de trabajo, aplicación). Obtienes un panel de gasto en tiempo real sin cambiar tu flujo de llamadas existente.

Grok Bot con acción de medios pagados no evadible

Grok Bot puede llamar herramientas MCP personalizadas, pero instalar las herramientas independientes de Cycles junto a un conector de medios pagados sigue siendo cooperativo: el Bot podría llamar al otro conector directamente. La puerta de enlace de medios pagados de Grok Bot muestra la forma de aplicación estricta en su lugar. Su manejador de mutación deriva el ámbito de la configuración confiable del servidor, requiere una reserva RISK_POINTS activa, propaga el ID de reserva a la API descendente y resuelve conservadoramente resultados ambiguos.

Instalación

npm install @runcycles/mcp-server

Configuración

Claude Desktop

Un clic (recomendado): descarga cycles-mcp-server-<version>.mcpb de la última versión y ábrela con Claude Desktop (doble clic, o Configuración → Extensiones → arrástrala). Claude Desktop muestra una pantalla de configuración para la URL de tu servidor Cycles y la clave API, o habilita el modo simulado para explorar las herramientas sin un servidor (sin aplicación).

Manual (configuración JSON): agrega a tu claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cycles": {
      "command": "npx",
      "args": ["-y", "@runcycles/mcp-server"],
      "env": {
        "CYCLES_BASE_URL": "http://localhost:7878",
        "CYCLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Para desarrollo local sin clave API, usa el modo simulado:

{
  "mcpServers": {
    "cycles": {
      "command": "npx",
      "args": ["-y", "@runcycles/mcp-server"],
      "env": {
        "CYCLES_MOCK": "true"
      }
    }
  }
}

Claude Code

claude mcp add cycles -- npx -y @runcycles/mcp-server

Establece tus variables de entorno:

export CYCLES_BASE_URL=http://localhost:7878
export CYCLES_API_KEY=your-api-key-here

Cursor / Windsurf / Otros hosts MCP

Usa transporte stdio con:

command: npx
args: ["-y", "@runcycles/mcp-server"]
env: { CYCLES_API_KEY: "your-key", CYCLES_BASE_URL: "http://localhost:7878" }

Configuración

export CYCLES_API_KEY=your-api-key-here       # required (unless CYCLES_MOCK=true)
export CYCLES_BASE_URL=http://localhost:7878   # required — your Cycles server URL
export CYCLES_MOCK=false                       # true disables live enforcement and returns synthetic responses
export CYCLES_ALLOW_MOCK_IN_PRODUCTION=false  # must be true to use mock mode with NODE_ENV=production
export PORT=3000                               # optional, for HTTP transport
export HOST=127.0.0.1                          # optional HTTP bind address; unset binds all interfaces
export MCP_HTTP_AUTH_TOKEN=replace-me          # optional bearer token required on /mcp when set

# Optional subject defaults — merged into any tool call that omits the field,
# so agents can call cycles_reserve with just an action and amount:
export CYCLES_DEFAULT_TENANT=acme
export CYCLES_DEFAULT_WORKSPACE=prod
export CYCLES_DEFAULT_APP=support-bot
export CYCLES_DEFAULT_WORKFLOW=
export CYCLES_DEFAULT_AGENT=
export CYCLES_DEFAULT_TOOLSET=

Comportamiento de ergonomía del agente: los campos de sujeto explícitos siempre ganan sobre los valores de CYCLES_DEFAULT_*, y cycles_check_balance acepta una llamada vacía cuando los valores predeterminados proporcionan un filtro. idempotencyKey sigue siendo obligatorio en cada herramienta de mutación: la reproducción con la misma clave es el mecanismo de deduplicación de reintentos y supresión de evidencia del protocolo, y solo el llamador puede mantener una clave estable entre reintentos. Las respuestas incluyen sugerencias en texto plano después de la carga JSON cuando el presupuesto está bajo presión (DENY, ALLOW_WITH_CAPS o menos de ~15% restante), para que los agentes se autorregulen sin soporte del host.

El modo simulado imprime una advertencia prominente en cada inicio, y los IDs de reserva/evento simulados generados comienzan con mock_. El servidor se niega a iniciar con CYCLES_MOCK=true y NODE_ENV=production a menos que CYCLES_ALLOW_MOCK_IN_PRODUCTION=true también esté configurado.

Para transporte HTTP, establece MCP_HTTP_AUTH_TOKEN para requerir Authorization: Bearer <token> en cada solicitud /mcp. Los tokens configurados en blanco o solo con espacios se rechazan al inicio. /health permanece público. Si no se configura ningún token mientras HTTP se vincula a una dirección no de bucle local, el servidor imprime una advertencia prominente.

¿Necesitas una clave API? Las claves API se crean mediante el Servidor de Administración de Cycles (puerto 7979). Consulta la guía de despliegue para crear una, o ejecuta:

curl -s -X POST http://localhost:7979/v1/admin/api-keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: admin-bootstrap-key" \
  -d '{"tenant_id":"acme-corp","name":"dev-key","permissions":["reservations:create","reservations:commit","reservations:release","reservations:extend","reservations:list","balances:read","decide","events:create"]}' | jq -r '.key_secret'

La clave (por ejemplo, cyc_live_abc123...) se muestra solo una vez: guárdala de inmediato. Para detalles sobre rotación y ciclo de vida de claves, consulta Gestión de Claves API.

Uso individual vs. de equipo: Para uso individual o evaluación, establece CYCLES_MOCK=true: no se requiere servidor ni clave API. Si estás desplegando agentes para múltiples usuarios o espacios de trabajo, consulta la guía de configuración multiinquilino.

Ejecución

# stdio transport (default — for Claude Desktop / Claude Code)
npx @runcycles/mcp-server

# HTTP transport (Streamable HTTP on port 3000)
npx @runcycles/mcp-server --transport http

Herramientas

Herramienta	Endpoint de Protocolo	Descripción
`cycles_reserve`	`POST /v1/reservations`	Reserva presupuesto antes de una operación costosa
`cycles_commit`	`POST /v1/reservations/{id}/commit`	Confirma el uso real después de que la operación se completa
`cycles_release`	`POST /v1/reservations/{id}/release`	Libera la reserva sin confirmar
`cycles_extend`	`POST /v1/reservations/{id}/extend`	Extiende el TTL de la reserva (latido)
`cycles_decide`	`POST /v1/decide`	Verificación de presupuesto previa ligera
`cycles_check_balance`	`GET /v1/balances`	Verifica el saldo de presupuesto actual para un ámbito
`cycles_list_reservations`	`GET /v1/reservations`	Lista reservas con filtros
`cycles_get_reservation`	`GET /v1/reservations/{id}`	Obtiene detalles de reserva por ID
`cycles_create_event`	`POST /v1/events`	Registra uso sin ciclo de reserva/confirmación

Bucle de Decisión del Agente

Cada operación costosa sigue un ciclo de vida de reservar → ejecutar → finalizar:

1. cycles_reserve   → Lock budget before each costly step
2. Execute          → Perform the operation (respecting any caps)
3. cycles_commit    → Record actual usage — releases unused portion back to the pool
   OR cycles_release → Cancel the reservation if the step was skipped

Opcionalmente, antes de reservar:

cycles_check_balance — inspecciona el presupuesto restante para planificar tu enfoque
cycles_decide — verificación previa ligera sin bloquear fondos

Cada reserva debe finalizarse con cycles_commit o cycles_release: nunca dejes reservas pendientes. Para operaciones de larga duración, usa cycles_extend para enviar latidos al TTL de la reserva para que no expire a mitad de la operación. Consulta patrones de integración para ejemplos detallados.

Modelo de Seguridad y Límite de Aplicación

La autoridad de Cycles se aplica en dos límites diferentes, y importa en cuál estás confiando.

Aplicado incondicionalmente (lado del servidor)

Cada llamada a cycles_reserve, cycles_commit y cycles_decide es una solicitud de autoridad, evaluada por el runtime de Cycles contra las políticas y saldos actuales del inquilino autenticado. Esto se mantiene independientemente de lo que genere el modelo:

Los montos malformados nunca salen del servidor MCP. Los esquemas de entrada rechazan montos negativos, fraccionarios o no numéricos, y cualquier valor por encima del rango de enteros seguros de JavaScript (2⁵³ − 1), antes de que se haga una solicitud.
Una reserva bien formada pero excesiva es rechazada por el servidor de Cycles con un error BUDGET_EXCEEDED: no se emite ningún ID de reserva y no se gasta nada. Una reserva alucinada o inyectada por prompt de tamaño excesivo no puede hacer que Cycles otorgue más autoridad de la que permite la política.
Una reserva por sí sola no gasta nada. El presupuesto solo se mueve en cycles_commit (o cycles_create_event), y las confirmaciones están limitadas por la reserva más la política de exceso configurada.

Cooperativo (dentro del bucle de herramientas del agente)

Este servidor MCP expone herramientas de presupuesto junto a las otras herramientas del host: no se sitúa entre el modelo y esas herramientas. Cuando se deniega una reserva, se instruye al agente a no proceder, pero nada en el protocolo MCP lo obliga. Un agente inyectado por prompt o con mal comportamiento podría omitir cycles_reserve por completo e invocar una herramienta consecuente directamente.

Haciendo la aplicación no evadible

Para que la verificación de presupuesto sea una puerta dura en lugar de una convención, coloca a Cycles en la ruta de despacho real para que la operación descendente no pueda ejecutarse sin una reserva válida:

Puerta en la aplicación host — antes de ejecutar una operación consecuente, requiere un ID de reserva y verifícalo con cycles_get_reservation.
Usa una integración en la ruta de despacho — el middleware del framework que envuelve la ejecución de herramientas (por ejemplo, el starter de Spring Boot de Cycles o la integración con LangChain) aplica reservar-antes-de-ejecutar en código que el modelo no puede omitir.
Mide del lado del servidor como respaldo — donde no sea posible la puerta, registra el uso real con cycles_create_event para que los excesos al menos se detecten y los presupuestos se mantengan precisos.

El modo simulado no aplica nada

Con CYCLES_MOCK=true, cada llamada devuelve un ALLOW sintético: existe solo para desarrollo y demostraciones. El servidor se niega a iniciar en modo simulado cuando NODE_ENV=production (a menos que se anule explícitamente) precisamente para que un ALLOW sintético nunca se confunda con uno real.

Recursos

URI	Descripción
`cycles://balances/{tenant}`	Saldo de presupuesto actual para un tenant
`cycles://reservations/{reservation_id}`	Detalles de la reserva
`cycles://docs/quickstart`	Guía de inicio rápido
`cycles://docs/patterns`	Patrones de integración

Prompts

Prompt	Descripción
`integrate_cycles`	Generar código de integración con Cycles
`diagnose_overrun`	Analizar agotamiento de presupuesto
`design_budget_strategy`	Recomendar jerarquía de scopes y límites

Desarrollo

npm install
npm run dev              # stdio transport with tsx
npm run dev:http         # HTTP transport with tsx
npm run build            # TypeScript build
npm run lint             # ESLint
npm test                 # Run tests
npm run test:coverage    # Run with coverage (95%+ lines, 85%+ branches)
npm run typecheck        # Type check without emitting

Publicación

El servidor se publica en dos registros:

Registro	Identificador	Cómo
npm	`@runcycles/mcp-server`	CI publica al hacer push de la etiqueta `v*` con procedencia
MCP Registry	`io.github.runcycles/cycles-mcp-server`	CI publica el manifiesto `server.json` después de npm

Los lanzamientos se automatizan con release-please. Los PRs se fusionan con squash (el repositorio solo permite squash) con títulos de PR convencionales (feat:, fix:, …) — el título del PR se convierte en el único commit en main que release-please lee. Mantiene un PR de lanzamiento que acumula el changelog y actualiza la versión en package.json, server.json (ambos campos) y el encabezado AUDIT.md. Fusionar el PR de lanzamiento crea la etiqueta y el release de GitHub, y luego ejecuta el pipeline de publicación.

CI se ejecuta en la etiqueta: pruebas (Node 20+22) → publicación en npm (Trusted Publishing/OIDC, con procedencia) → prueba de humo contra el tarball publicado → publicación en MCP Registry → bundle de extensión de escritorio MCPB adjunto al release de GitHub.

Respaldo manual (funciona sin cambios): actualiza las versiones tú mismo, luego etiqueta y haz push:

git tag v0.5.0
git push origin v0.5.0

Documentación

Documentación de Cycles — sitio completo de documentación
Inicio rápido del servidor MCP — guía de inicio rápido
Integración de Cycles con MCP — guía detallada de integración con MCP

Conformidad con el Protocolo

Este servidor MCP está auditado contra la especificación OpenAPI del Protocolo Cycles v0.1.24. Consulta AUDIT.md para el informe completo de conformidad.

Política de Privacidad

Política completa: runcycles.io/privacy

La versión corta: este servidor se conecta solo a la URL del servidor Cycles que configures y le envía solicitudes de presupuesto (identificadores de sujeto, montos, métricas de uso) — Cycles se aloja en tu propia infraestructura, por lo que esos datos permanecen en tu infraestructura y nunca llegan a runcycles. No se almacenan prompts ni respuestas de LLM. El servidor no contiene telemetría, llamadas a casa ni comprobaciones de actualización. En modo mock, no se realizan solicitudes de red en absoluto. Tu clave de API vive en tu configuración local y se envía solo a tu servidor Cycles configurado.

Licencia

Apache-2.0