Cycles MCP Server

Autoridade de orçamento de tempo de execução para agentes de IA — reservar, aplicar e rastrear gastos antes de cada chamada de LLM e invocação de ferramenta.

GitHub

Documentação

Cycles MCP Server — Controle de runtime de agentes de IA via Model Context Protocol

Servidor MCP que dá a qualquer agente de IA compatível com MCP (Claude Code, Cursor, Windsurf, agentes personalizados) autoridade de runtime sobre orçamento, ações e auditoria — imponha limites de custo de LLM, limites de chamadas de ferramentas, permissões de ações e trilhas de auditoria antes da execução, sem alterar o código do agente. Conecte via MCP e use as ferramentas de orçamento (cycles_reserve, cycles_commit, cycles_release, cycles_decide) diretamente no loop de chamada de ferramentas do agente. Desenvolvido por Cycles. Consulte Modelo de Segurança e Limite de Execução para saber o que é imposto no lado do servidor versus cooperativamente no loop do agente.

Por que usar isso?

Agentes de IA autônomos (Claude, GPT, agentes personalizados) chamam LLMs, invocam ferramentas e acessam APIs externas — mas não têm uma forma nativa de limitar quanto gastam. Um único loop de agente pode queimar centenas de dólares antes que alguém perceba. Multiplique isso entre locatários e equipes, e o controle de custos se torna um problema real.

Este servidor MCP dá a qualquer agente compatível com MCP uma autoridade de orçamento em runtime: um conjunto de ferramentas para verificar, reservar, gastar e liberar orçamento antes e depois de cada operação custosa. O agente pergunta "posso pagar por isso?" antes de agir e reporta o que realmente usou depois.

Quem precisa disso:

Equipes de plataforma que constroem sistemas de agentes multi-locatário que precisam de limites de gastos por cliente ou por workspace
Desenvolvedores de agentes que querem que os agentes se autorregulem — degradem para modelos mais baratos quando o orçamento está baixo, pulem chamadas de ferramentas opcionais, reduzam tentativas
Empresas que implantam agentes de IA e precisam de proteções para que um agente descontrolado não estoure o orçamento

Por que MCP especificamente:

MCP é o protocolo padrão que hosts de IA (Claude Desktop, Claude Code, Cursor, Windsurf, agentes personalizados) usam para descobrir e chamar ferramentas. Ao expor o Cycles como um servidor MCP, qualquer agente compatível com MCP ganha consciência de orçamento como um plug-in — basta adicionar o servidor à sua configuração. Nenhuma integração de SDK no código do próprio agente é necessária.

O servidor também inclui prompts integrados para que um assistente de IA possa ajudá-lo a projetar sua estratégia de orçamento, gerar código de integração e diagnosticar estouros de orçamento — não apenas impor orçamentos em runtime.

Casos de Uso

Agente de codificação com limite de dólares por tarefa

Você executa um agente Claude Code que escreve e itera sobre código. Cada tarefa deve custar no máximo $5. O agente chama cycles_reserve antes de cada chamada de LLM com uma estimativa de custo em USD_MICROCENTS. Se a reserva retornar DENY, o agente para e reporta "orçamento esgotado" em vez de silenciosamente acumular cobranças. Quando a chamada é concluída, cycles_commit registra o custo real de tokens para que o total acumulado permaneça preciso.

SaaS multi-locatário com orçamentos por cliente

Sua plataforma permite que clientes implantem assistentes de IA. Cada cliente tem um orçamento mensal. O agente chama cycles_check_balance no início de uma conversa para ver o que resta, depois cycles_reserve antes de cada invocação de ferramenta (busca na web, execução de código, chamadas de API). Se o cliente Acme estiver perto do limite, a decisão retorna ALLOW_WITH_CAPS — o agente automaticamente cai para um modelo mais barato e pula ferramentas opcionais. Os orçamentos dos clientes são isolados; o uso intenso de um cliente nunca afeta outro.

Pipeline multi-agente com orçamento compartilhado

Você tem um orquestrador que distribui trabalho para agentes especialistas — um pesquisador, um codificador e um revisor. Todos os três usam o mesmo orçamento de fluxo de trabalho. Cada agente chama cycles_reserve antes de seu trabalho; o servidor Cycles rastreia reservas concorrentes para que o total nunca exceda o limite do fluxo de trabalho. Se o pesquisador consumir 80% do orçamento, a próxima reserva do codificador recebe DENY e o orquestrador pode decidir pular a etapa de revisão em vez de estourar o orçamento.

Pipeline de dados de longa duração com heartbeats

Um agente processa um grande conjunto de dados em blocos, cada bloco levando vários minutos. Ele chama cycles_reserve com um TTL de 5 minutos antes de cada bloco, depois cycles_extend a cada 60 segundos para manter a reserva viva durante o processamento. Se o agente travar, a reserva expira automaticamente e o orçamento bloqueado retorna ao pool — sem necessidade de limpeza manual.

Medição de uso fire-and-forget

Você tem um sistema existente que já faz chamadas de LLM e só quer rastrear gastos, não bloqueá-los. Após cada chamada ser concluída, o agente dispara cycles_create_event com o custo real. Nenhuma reserva é necessária — o evento é aplicado atomicamente a todos os escopos de orçamento (locatário, workspace, aplicativo). Você obtém um painel de gastos em tempo real sem alterar seu fluxo de chamadas existente.

Grok Bot com ação de mídia paga não contornável

O Grok Bot pode chamar ferramentas MCP personalizadas, mas instalar as ferramentas Cycles standalone ao lado de um conector de mídia paga permanece cooperativo: o Bot poderia chamar o outro conector diretamente. O gateway de mídia paga do Grok Bot mostra a forma de imposição rígida. Seu manipulador de mutação deriva o escopo da configuração confiável do servidor, exige uma reserva RISK_POINTS ativa, propaga o ID da reserva para a API downstream e liquida conservadoramente resultados ambíguos.

Instalação

npm install @runcycles/mcp-server

Configuração

Claude Desktop

Um clique (recomendado): baixe cycles-mcp-server-<version>.mcpb da última versão e abra com o Claude Desktop (duplo clique, ou Configurações → Extensões → arraste-o). O Claude Desktop mostra uma tela de configuração para a URL do seu servidor Cycles e chave de API — ou ative o modo mock para explorar as ferramentas sem um servidor (sem imposição).

Manual (config JSON): adicione ao seu 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 desenvolvimento local sem chave de API, use o modo mock:

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

Claude Code

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

Defina suas variáveis de ambiente:

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

Cursor / Windsurf / Outros Hosts MCP

Use transporte stdio com:

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

Configuração

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=

Comportamento de ergonomia do agente: campos de assunto explícitos sempre vencem valores de CYCLES_DEFAULT_*, e cycles_check_balance aceita uma chamada vazia quando os padrões fornecem um filtro. idempotencyKey permanece obrigatório em toda ferramenta de mutação — a repetição com a mesma chave é o mecanismo de deduplicação de tentativas e supressão de evidências do protocolo, e apenas o chamador pode manter uma chave estável entre tentativas. As respostas carregam dicas em texto simples após o payload JSON quando o orçamento está sob pressão (DENY, ALLOW_WITH_CAPS, ou abaixo de ~15% restante), para que os agentes se autorregulem sem suporte do host.

O modo mock imprime um aviso proeminente em cada inicialização, e os IDs gerados de reserva/evento mock começam com mock_. O servidor se recusa a iniciar com CYCLES_MOCK=true e NODE_ENV=production a menos que CYCLES_ALLOW_MOCK_IN_PRODUCTION=true também esteja definido.

Para transporte HTTP, defina MCP_HTTP_AUTH_TOKEN para exigir Authorization: Bearer <token> em cada requisição /mcp. Tokens configurados em branco ou apenas com espaços são rejeitados na inicialização. /health permanece público. Se nenhum token for configurado enquanto o HTTP vincula a um endereço não-loopback, o servidor imprime um aviso proeminente.

Precisa de uma chave de API? As chaves de API são criadas via Cycles Admin Server (porta 7979). Consulte o guia de implantação para criar uma, ou execute:

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'

A chave (ex.: cyc_live_abc123...) é mostrada apenas uma vez — salve-a imediatamente. Para detalhes de rotação e ciclo de vida de chaves, consulte Gerenciamento de Chaves de API.

Uso individual vs. equipe: Para uso individual ou avaliação, defina CYCLES_MOCK=true — nenhum servidor ou chave de API é necessário. Se você está implantando agentes para múltiplos usuários ou workspaces, consulte o guia de configuração multi-locatário.

Execução

# 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

Ferramentas

Ferramenta	Endpoint do Protocolo	Descrição
`cycles_reserve`	`POST /v1/reservations`	Reserva orçamento antes de uma operação custosa
`cycles_commit`	`POST /v1/reservations/{id}/commit`	Registra o uso real após a conclusão da operação
`cycles_release`	`POST /v1/reservations/{id}/release`	Libera a reserva sem registrar
`cycles_extend`	`POST /v1/reservations/{id}/extend`	Estende o TTL da reserva (heartbeat)
`cycles_decide`	`POST /v1/decide`	Verificação de orçamento leve antes da operação
`cycles_check_balance`	`GET /v1/balances`	Verifica o saldo atual de orçamento para um escopo
`cycles_list_reservations`	`GET /v1/reservations`	Lista reservas com filtros
`cycles_get_reservation`	`GET /v1/reservations/{id}`	Obtém detalhes da reserva por ID
`cycles_create_event`	`POST /v1/events`	Registra uso sem ciclo de reserva/registro

Loop de Decisão do Agente

Toda operação custosa segue um ciclo de vida de reserva → execução → finalização:

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 — inspecione o orçamento restante para planejar sua abordagem
cycles_decide — verificação leve sem bloquear fundos

Toda reserva deve ser finalizada com cycles_commit ou cycles_release — nunca deixe reservas pendentes. Para operações de longa duração, use cycles_extend para enviar heartbeat ao TTL da reserva para que ela não expire no meio da operação. Consulte padrões de integração para exemplos detalhados.

Modelo de Segurança e Limite de Execução

A autoridade do Cycles é imposta em dois limites diferentes, e importa em qual você está confiando.

Imposto incondicionalmente (lado do servidor)

Toda chamada de cycles_reserve, cycles_commit e cycles_decide é uma solicitação de autoridade, avaliada pelo runtime do Cycles contra as políticas e saldos atuais do locatário autenticado. Isso vale independentemente do que o modelo gera:

Valores malformados nunca saem do servidor MCP. Os esquemas de entrada rejeitam valores negativos, fracionários ou não numéricos, e qualquer valor acima do intervalo de inteiros seguros do JavaScript (2⁵³ − 1), antes que uma requisição seja feita.
Uma reserva bem formada, mas excessiva, é recusada pelo servidor Cycles com um erro BUDGET_EXCEEDED — nenhum ID de reserva é emitido e nada é gasto. Uma reserva alucinada ou injetada por prompt não pode fazer o Cycles conceder mais autoridade do que a política permite.
Uma reserva por si só não gasta nada. O orçamento só se move em cycles_commit (ou cycles_create_event), e os registros são limitados pela reserva mais a política de excesso configurada.

Cooperativo (dentro do loop de ferramentas do agente)

Este servidor MCP expõe ferramentas de orçamento junto com as outras ferramentas do host — ele não fica entre o modelo e essas ferramentas. Quando uma reserva é negada, o agente é instruído a não prosseguir, mas nada no protocolo MCP o força. Um agente com prompt injetado ou malcomportado poderia pular cycles_reserve completamente e invocar uma ferramenta consequente diretamente.

Tornando a imposição não contornável

Para que a verificação de orçamento seja um portão rígido em vez de uma convenção, coloque o Cycles no caminho real de despacho para que a operação downstream não possa ser executada sem uma reserva válida:

Portão no aplicativo host — antes de executar uma operação consequente, exija um ID de reserva e verifique-o com cycles_get_reservation.
Use uma integração no caminho de despacho — middleware de framework que envolve a execução de ferramentas (ex.: o starter Spring Boot do Cycles ou a integração LangChain) impõe reserva-antes-de-executar em código que o modelo não pode pular.
Meça no lado do servidor como rede de segurança — onde o bloqueio não é possível, registre o uso real com cycles_create_event para que estouros sejam pelo menos detectados e os orçamentos permaneçam precisos.

O modo mock não impõe nada

Com CYCLES_MOCK=true, toda chamada retorna um ALLOW sintético — ele existe apenas para desenvolvimento e demonstrações. O servidor se recusa a iniciar em modo mock quando NODE_ENV=production (a menos que explicitamente sobrescrito) precisamente para que um ALLOW sintético nunca seja confundido com um real.

Recursos

URI	Descrição
`cycles://balances/{tenant}`	Saldo atual do orçamento para um locatário
`cycles://reservations/{reservation_id}`	Detalhes da reserva
`cycles://docs/quickstart`	Guia de introdução
`cycles://docs/patterns`	Padrões de integração

Prompts

Prompt	Descrição
`integrate_cycles`	Gerar código de integração com Cycles
`diagnose_overrun`	Analisar esgotamento do orçamento
`design_budget_strategy`	Recomendar hierarquia de escopos e limites

Desenvolvimento

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

Publicação

O servidor é publicado em dois registros:

Registro	Identificador	Como
npm	`@runcycles/mcp-server`	CI publica no push da tag `v*` com proveniência
MCP Registry	`io.github.runcycles/cycles-mcp-server`	CI publica o manifesto `server.json` após o npm

Os lançamentos são automatizados com release-please. PRs são mesclados com squash (o repositório exige apenas squash) com títulos de PR convencionais (feat:, fix:, …) — o título do PR se torna o único commit em main que o release-please lê. Ele mantém um PR de lançamento que acumula o changelog e incrementa a versão em package.json, server.json (ambos os campos) e no cabeçalho AUDIT.md. Mesclar o PR de lançamento cria a tag e o release do GitHub e, em seguida, dispara o pipeline de publicação.

O CI é executado na tag: teste (Node 20+22) → publicação no npm (Trusted Publishing/OIDC, com proveniência) → teste de fumaça contra o tarball publicado → publicação no MCP Registry → pacote de extensão de desktop MCPB anexado ao release do GitHub.

Fallback manual (funciona sem alterações): incremente as versões você mesmo e depois crie a tag e faça o push:

git tag v0.5.0
git push origin v0.5.0

Documentação

Documentação do Cycles — site completo de documentação
Início rápido do MCP Server — guia de introdução
Integrando Cycles com MCP — guia detalhado de integração com MCP

Conformidade com o Protocolo

Este servidor MCP é auditado contra a especificação OpenAPI do Cycles Protocol v0.1.24. Consulte AUDIT.md para o relatório completo de conformidade.

Política de Privacidade

Política completa: runcycles.io/privacy

A versão resumida: este servidor se conecta apenas à URL do servidor Cycles que você configurar e envia a ele solicitações de orçamento (identificadores de assunto, valores, métricas de uso) — o Cycles é auto-hospedado, portanto esses dados permanecem na sua infraestrutura e nunca chegam ao runcycles. Nenhum prompt ou resposta de LLM é armazenado. O servidor não contém telemetria, comunicação com servidores externos ou verificações de atualização. No modo mock, nenhuma solicitação de rede é feita. Sua chave de API fica na sua configuração local e é enviada apenas ao servidor Cycles configurado.

Licença

Apache-2.0