MCP SERVER · OFFICIAL PROJECTGive an agent a budget it has to ask for: reserve before the call, commit what it actually spent.
LABSCO SUMMARY
Malformed and excessive amounts are rejected before anything is issued, and a reservation on its own spends nothing — budget only moves on a commit. What the protocol cannot do is stop an agent from skipping the check entirely, which the project says outright and answers by putting Cycles in the dispatch path.
A budget authority for agent loops. Before a costly step — an LLM call, a tool invocation, an external action — the agent reserves against a scope; afterwards it commits the real usage or releases the hold. Scopes nest from tenant down through workspace, app, workflow, agent and toolset, so a per-customer or per-task cap is enforced by the Cycles runtime rather than by prompt.
Node.js 20 or newer, run over stdio from npm as @runcycles/mcp-server, or with --transport http for streamable HTTP. Two variables are required in live use: CYCLES_API_KEY and CYCLES_BASE_URL pointing at your Cycles server. CYCLES_MOCK=true explores the tools with no server and no key, prefixing generated IDs with mock_ and enforcing nothing; it is refused under NODE_ENV=production unless CYCLES_ALLOW_MOCK_IN_PRODUCTION is also set. CYCLES_DEFAULT_TENANT and its siblings fill in subject fields an agent omits, and explicit fields win. Every mutating call requires an idempotencyKey — only the caller can hold one stable across a retry. On HTTP, MCP_HTTP_AUTH_TOKEN makes a bearer token mandatory on /mcp while /health stays public.
One command plus a key — npx -y @runcycles/mcp-server, then supply credentials
USE CASES
Reserve against the task before each model call with an estimate; on a denial the agent stops and says so instead of quietly running up the bill, and the commit keeps the running total honest.
Read the tenant's balance at the start of a conversation and reserve per tool call; when they are near the limit the decision comes back capped and the agent drops to a cheaper path.
Researcher, coder and reviewer each reserve from the same workflow scope, so concurrent holds are counted and the last one gets denied rather than the total going over.
Reserve with a TTL for each chunk and heartbeat it while the chunk runs; a crash lets the hold expire and returns the money with no cleanup.
Ask whether the expensive route would be allowed at all, without locking funds, and pick the strategy from the answer.
Record each completed call as an event after the fact — no reservation, applied to every scope at once — and audit later by listing what came through.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
cycles_check_balanceCheck 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_commitCommit 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_create_eventRecord 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.
cycles_decideLightweight 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_extendExtend 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_get_reservationGet 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_list_reservationsList reservations, optionally filtered by status (ACTIVE, COMMITTED, RELEASED, EXPIRED) or subject fields. Useful for debugging stuck reservations or auditing budget usage.
cycles_releaseRelease 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_reserveReserve 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.
BEFORE YOU INSTALL
9 tools when we connected. With CYCLES_MOCK=true all nine tools still answer, but live budget enforcement is off and reservation and event IDs carry a mock_ prefix.
CONTEXT COST
Rated by the size of the 9 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y @runcycles/mcp-server{
"mcpServers": {
"cycles": {
"command": "npx",
"args": [
"-y",
"@runcycles/mcp-server"
],
"env": {
"CYCLES_BASE_URL": "http://localhost:7878",
"CYCLES_API_KEY": "<YOUR_CYCLES_API_KEY>"
}
}
}
}{
"mcpServers": {
"cycles": {
"command": "npx",
"args": [
"-y",
"@runcycles/mcp-server"
],
"env": {
"CYCLES_MOCK": "true"
}
}
}
}claude mcp add cycles -- npx -y @runcycles/mcp-server{
"mcpServers": {
"cycles-mcp-server": {
"command": "npx",
"args": [
"-y",
"@runcycles/mcp-server"
],
"env": {
"CYCLES_API_KEY": "<YOUR_CYCLES_API_KEY>",
"CYCLES_BASE_URL": "http://localhost:7878"
}
}
}
}npx @runcycles/mcp-server --transport httpMCP servers
rtahabas
gabrielmahia
Modexia
agentc22