Cycles MCP Server
About
Runtime budget authority for AI agents — reserve, enforce, and track spend before every LLM call and tool invocation.
Explore
- Platform teams building multi-tenant agent systems that need per-customer or per-workspace spend limits
- Enterprises deploying AI agents that need guardrails so a runaway agent can't blow through a budget
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- cycles_check_balance — inspect remaining budget to plan your approach
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Cycles MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
An agent processes a large dataset in chunks, each chunk taking several minutes. It callscycles_reservewith a 5-minute TTL before each chunk, thencycles_extendevery 60 seconds to keep the reservation alive while processing. If the agent crashes, the reservation expires automatically and the locked budget returns to the pool — no manual cleanup needed.
You have an existing system that already makes LLM calls and you just want to track spend, not gate it. After each call completes, the agent firescycles_create_eventwith the actual cost. No reservation needed — the event is applied atomically to all budget scopes (tenant, workspace, app). You get a real-time spend dashboard without changing your existing call flow.
One-click (recommended):downloadcycles-mcp-server-<version>.mcpbfrom the](#prompts)latest releaseand open it with Claude Desktop (double-click, or Settings → Extensions → drag it in). Claude Desktop shows a config screen for your Cycles server URL and API key — or enable mock mode to explore the tools without a server (no enforcement).
Manual (JSON config):add to yourclaude_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" } } } }
For local development without an API key, use mock mode:
{ "mcpServers": { "cycles": { "command": "npx", "args": ["-y", "@runcycles/mcp-server"], "env": { "CYCLES_MOCK": "true" } } } }
claude mcp add cycles -- npx -y @runcycles/mcp-server
export CYCLES_BASE_URL=http://localhost:7878 export CYCLES_API_KEY=your-api-key-here
command: npx args: ["-y", "@runcycles/mcp-server"] env: { CYCLES_API_KEY: "your-key", CYCLES_BASE_URL: "http://localhost:7878" }
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=
Agent-ergonomics behavior: explicit subject fields always win overCYCLES_DEFAULT_*values, andcycles_check_balanceaccepts an empty call when defaults supply a filter.idempotencyKeyremainsrequired on every mutating tool— same-key replay is the protocol's retry deduplication and evidence-suppression mechanism, and only the caller can hold a key stable across retries. Responses carry plain-text hints after the JSON payload when the budget is under pressure (DENY,ALLOW_WITH_CAPS, or under ~15% remaining), so agents self-regulate without host support.
Mock mode prints a prominent warning on every startup, and generated mock reservation/event IDs begin withmock_. The server refuses to start withCYCLES_MOCK=trueandNODE_ENV=productionunlessCYCLES_ALLOW_MOCK_IN_PRODUCTION=trueis also set.
For HTTP transport, setMCP_HTTP_AUTH_TOKENto requireAuthorization: Bearer <token>on every/mcprequest. Blank or whitespace-only configured tokens are rejected at startup./healthremains public. If no token is configured while HTTP binds to a non-loopback address, the server prints a prominent warning.
Need an API key?API keys are created via the Cycles Admin Server (port 7979). See thedeployment guideto create one, or run:
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'
The key (e.g.cyc_live_abc123...) is shown only once — save it immediately. For key rotation and lifecycle details, seeAPI Key Management.
Individual vs. team use:For individual use or evaluation, setCYCLES_MOCK=true— no server or API key required. If you're deploying agents for multiple users or workspaces, see themulti-tenant setup guide.
# 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
Every costly operation follows a reserve → execute → finalize lifecycle:
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
- cycles_check_balance— inspect remaining budget to plan your approach
- cycles_decide— lightweight preflight check without locking funds
Every reservationmustbe finalized with eithercycles_commitorcycles_release— never leave reservations dangling. For long-running operations, usecycles_extendto heartbeat the reservation TTL so it doesn't expire mid-operation. See[integration patternsfor detailed examples.
cycles_reserve
Reserve budget before a costly operation (LLM call, tool invocation, external action). Returns a reservation_id to commit or release later. If decision is not ALLOW, do not proceed with the operation. For lightweight preflight checks without reserving, use cycles_decide instead.
cycles_commit
Commit actual usage after an operation completes. Always call this after cycles_reserve whether the operation succeeded or failed. Finalizes the budget charge and releases any unused reserved amount back to the pool.
cycles_release
Release a reservation without committing. Use when an operation is cancelled, skipped, or fails before execution. Returns the released budget amount back to the pool.
cycles_extend
Extend the TTL of an active reservation. Use as a heartbeat for long-running operations to prevent the reservation from expiring. Does not change the reserved amount.
cycles_decide
Lightweight preflight check — ask whether an action would be allowed without reserving budget. Does not create a reservation. Use at workflow start to decide strategy. For concurrency-safe budget locking, use cycles_reserve instead.
cycles_check_balance
Check current budget balance for a scope. Returns remaining, reserved, spent, allocated, and debt amounts. At least one subject filter (tenant, workspace, app, workflow, agent, or toolset) is required. Do not use as a substitute for cycles_reserve — balances can change between check and action.
cycles_list_reservations
List reservations, optionally filtered by status (ACTIVE, COMMITTED, RELEASED, EXPIRED) or subject fields. Useful for debugging stuck reservations or auditing budget usage.
cycles_get_reservation
Get details of a specific reservation by ID. Returns status, subject, action, reserved amount, timestamps, and affected scopes. Useful for debugging and monitoring long-running operations.
cycles_create_event
Record a usage event directly without the reserve/commit lifecycle. Use for fire-and-forget metering of completed operations where pre-estimation is not available. The event is applied atomically to all derived scopes.
This MCP server exposes budget toolsalongsidethe host's other tools — it does not sit between the model and those tools. When a reservation is denied, the agent is instructed not to proceed, but nothing in the MCP protocol forces it to. A prompt-injected or misbehaving agent could skipcycles_reserveentirely and invoke a consequential tool directly.
For the budget check to be a hard gate rather than a convention, put Cycles in the actual dispatch path so the downstream operation cannot execute without a valid reservation:
- Gate in the host application— before executing a consequential operation, require a reservation ID and verify it withcycles_get_reservation.
- Use a dispatch-path integration— framework middleware that wraps tool execution (e.g. the Cycles Spring Boot starter or LangChain integration) enforces reserve-before-execute in code the model cannot skip.
- Meter server-side as a backstop— where gating isn't possible, record actual usage withcycles_create_eventso overruns are at least detected and budgets stay accurate.
WithCYCLES_MOCK=true, every call returns a syntheticALLOW— it exists for development and demos only. The server refuses to start in mock mode whenNODE_ENV=production(unless explicitly overridden) precisely so a syntheticALLOWis never mistaken for a real one.
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
The server is published to two registries:
Releases are automated with](https://github.com/runcycles/cycles-mcp-server/blob/HEAD/docs/patterns.md)release-please. PRs aresquash-merged(repo enforces squash-only) withconventional PR titles(feat:,fix:, …) — the PR title becomes the single commit onmainthat release-please reads. It maintains a release PR that accumulates the changelog and bumps the version inpackage.json,server.json(both fields), and theAUDIT.mdheader.Merging the release PRcreates the tag and GitHub release, then dispatches the publish pipeline.
CI runs on the tag: test (Node 20+22) → npm publish (Trusted Publishing/OIDC, with provenance) → smoke test against the published tarball → MCP Registry publish → MCPB desktop-extension bundle attached to the GitHub release.
Manual fallback (works unchanged): bump versions yourself, then tag and push:
- Cycles Documentation— full docs site
- MCP Server Quickstart— getting started guide
- Integrating Cycles with MCP— detailed MCP integration guide
This MCP server is audited against the Cycles Protocol v0.1.24 OpenAPI spec. SeeAUDIT.mdfor the full conformance report.
The short version: this server connects only to the Cycles server URL you configure and sends it budget requests (subject identifiers, amounts, usage metrics) — Cycles is self-hosted, so that data stays in your infrastructure and never reaches runcycles. No LLM prompts or responses are stored. The server contains no telemetry, phone-home, or update checks. In mock mode, no network requests are made at all. Your API key lives in your local configuration and is sent only to your configured Cycles server.
Interact with task, doc, and project data in Dart, an AI-native project management tool
Create notes, search, & think with your Fabric AI workspace
Great Question is an Agentic UX research platform for product builders. Its MCP lets AI agents create studies directly from any AI tool, surface insights, find the right research candidates, and query your entire research repository.
Magica is your all-in-one AI platform, offering 2500+ cutting-edge tools under a single subscription.
Prompt Buddy MCP exposes a public, searchable catalog of reusable AI skills.
Connect to the Taskade platform via MCP. Access tasks, projects, workflows, and AI agents in real-time through a unified workspace and API.
Dynamically search and call tools using UnifAI Network
A dynamic server for managing multi-agent collaboration within tmux sessions, featuring flexible pane configurations and auto-detection.
Provides AI assistants with advanced task management and memory capabilities using local JSON file storage.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"cycles mcp server": {
"cycles-mcp-server": {
"command": "npx",
"args": [
"@runcycles/mcp-server"
]
}
}
}
}McpServers
{
"cycles-mcp-server": {
"command": "npx",
"args": [
"@runcycles/mcp-server"
]
}
}MCP server that gives any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, custom agents) runtime budget, action, and audit authority — enforce LLM cost limits, tool call caps, action permissions, and audit trails before execution, with zero agent code changes.Connect via MCP and use the budget tools (cycles_reserve,cycles_commit,cycles_release,cycles_decide) directly from the agent's tool-calling loop. Powered byCycles. SeeSecurity Model & Enforcement Boundaryfor what is enforced server-side versus cooperatively in the agent loop.
Autonomous AI agents (Claude, GPT, custom agents) call LLMs, invoke tools, and hit external APIs — but have no built-in way to cap how much they spend. A single agent loop can burn through hundreds of dollars before anyone notices. Multiply that across tenants and teams, and cost control becomes a real problem.
This MCP server gives any MCP-compatible agent aruntime budget authority: a set of tools to check, reserve, spend, and release budget before and after every costly operation. The agent asks "can I afford this?" before acting, and reports what it actually used afterward.
- Platform teamsbuilding multi-tenant agent systems that need per-customer or per-workspace spend limits
- Agent developerswho want agents to self-regulate — degrade to cheaper models when budget is low, skip optional tool calls, reduce retries
- Enterprisesdeploying AI agents that need guardrails so a runaway agent can't blow through a budget
MCP is the standard protocol that AI hosts (Claude Desktop, Claude Code, Cursor, Windsurf, custom agents) use to discover and call tools. By exposing Cycles as an MCP server, any MCP-compatible agent gets budget awareness as a plug-in — just add the server to your config. No SDK integration in the agent's own code required.
The server also ships built-inpromptsso an AI assistant can help you design your budget strategy, generate integration code, and diagnose budget overruns — not just enforce budgets at runtime.
You run a Claude Code agent that writes and iterates on code. Each task should cost no more than $5. The agent callscycles_reservebefore every LLM call with a cost estimate inUSD_MICROCENTS. If the reservation comes backDENY, the agent stops and reports "budget exhausted" instead of silently racking up charges. When the call completes,cycles_commitrecords the actual token cost so the running total stays accurate.
Multi-tenant SaaS with per-customer budgets
Your platform lets customers deploy AI assistants. Each customer has a monthly budget. The agent callscycles_check_balanceat the start of a conversation to see what's left, thencycles_reservebefore each tool invocation (web search, code execution, API calls). If customer Acme is near their limit, the decision comes backALLOW_WITH_CAPS— the agent automatically drops to a cheaper model and skips optional tools. Customer budgets are isolated; one customer's heavy usage never affects another.
You have an orchestrator that fans out to specialist agents — a researcher, a coder, and a reviewer. All three draw from the same workflow budget. Each agent callscycles_reservebefore its work; the Cycles server tracks concurrent reservations so the total never exceeds the workflow limit. If the researcher burns through 80% of the budget, the coder's next reservation getsDENYand the orchestrator can decide to skip the review step instead of going over budget.
Long-running data pipeline with heartbeats
An agent processes a large dataset in chunks, each chunk taking several minutes. It callscycles_reservewith a 5-minute TTL before each chunk, thencycles_extendevery 60 seconds to keep the reservation alive while processing. If the agent crashes, the reservation expires automatically and the locked budget returns to the pool — no manual cleanup needed.
You have an existing system that already makes LLM calls and you just want to track spend, not gate it. After each call completes, the agent firescycles_create_eventwith the actual cost. No reservation needed — the event is applied atomically to all budget scopes (tenant, workspace, app). You get a real-time spend dashboard without changing your existing call flow.
One-click (recommended):downloadcycles-mcp-server-<version>.mcpbfrom thelatest releaseand open it with Claude Desktop (double-click, or Settings → Extensions → drag it in). Claude Desktop shows a config screen for your Cycles server URL and API key — or enable mock mode to explore the tools without a server (no enforcement).
Manual (JSON config):add to yourclaude_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" } } } }
For local development without an API key, use mock mode:
{ "mcpServers": { "cycles": { "command": "npx", "args": ["-y", "@runcycles/mcp-server"], "env": { "CYCLES_MOCK": "true" } } } }
claude mcp add cycles -- npx -y @runcycles/mcp-server
export CYCLES_BASE_URL=http://localhost:7878 export CYCLES_API_KEY=your-api-key-here
command: npx args: ["-y", "@runcycles/mcp-server"] env: { CYCLES_API_KEY: "your-key", CYCLES_BASE_URL: "http://localhost:7878" }
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=
Agent-ergonomics behavior: explicit subject fields always win overCYCLES_DEFAULT_*values, andcycles_check_balanceaccepts an empty call when defaults supply a filter.idempotencyKeyremainsrequired on every mutating tool— same-key replay is the protocol's retry deduplication and evidence-suppression mechanism, and only the caller can hold a key stable across retries. Responses carry plain-text hints after the JSON payload when the budget is under pressure (DENY,ALLOW_WITH_CAPS, or under ~15% remaining), so agents self-regulate without host support.
Mock mode prints a prominent warning on every startup, and generated mock reservation/event IDs begin withmock_. The server refuses to start withCYCLES_MOCK=trueandNODE_ENV=productionunlessCYCLES_ALLOW_MOCK_IN_PRODUCTION=trueis also set.
For HTTP transport, setMCP_HTTP_AUTH_TOKENto requireAuthorization: Bearer <token>on every/mcprequest. Blank or whitespace-only configured tokens are rejected at startup./healthremains public. If no token is configured while HTTP binds to a non-loopback address, the server prints a prominent warning.
Need an API key?API keys are created via the Cycles Admin Server (port 7979). See thedeployment guideto create one, or run:
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'
The key (e.g.cyc_live_abc123...) is shown only once — save it immediately. For key rotation and lifecycle details, seeAPI Key Management.
Individual vs. team use:For individual use or evaluation, setCYCLES_MOCK=true— no server or API key required. If you're deploying agents for multiple users or workspaces, see themulti-tenant setup guide.
# 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
Every costly operation follows a reserve → execute → finalize lifecycle:
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
- cycles_check_balance— inspect remaining budget to plan your approach
- cycles_decide— lightweight preflight check without locking funds
Every reservationmustbe finalized with eithercycles_commitorcycles_release— never leave reservations dangling. For long-running operations, usecycles_extendto heartbeat the reservation TTL so it doesn't expire mid-operation. See[integration patternsfor detailed examples.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
