Getting Started with the Cycles MCP Server

The Cycles MCP Server gives any MCP-compatible AI agent runtime budget authority. Instead of integrating an SDK into your application code, you add the MCP server to your agent's tool configuration and the agent gets direct access to budget tools — reserve, commit, release, check balance, and more.

This is the fastest way to add budget awareness to an AI agent. One config change, zero code changes.

Prerequisites

You need a running Cycles stack with a tenant, API key, and budget. If you don't have one yet, follow Deploy the Full Stack first.

Where do I get my API key?

API keys are created through the Cycles Admin Server (port 7979) and always start with cyc_live_. If your stack is already running with a tenant, create one directly:

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": "mcp-key",
    "permissions": ["reservations:create","reservations:commit","reservations:release","reservations:extend","reservations:list","balances:read","decide","events:create"]
  }' | jq -r '.key_secret'

The response returns the full key (e.g. cyc_live_abc123...). Save it — the secret is only shown once.

Need the full setup? See Deploy the Full Stack — Create an API key. For rotation and lifecycle details, see API Key Management.

Setup

Claude Desktop

Add to your 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_API_KEY": "cyc_live_..."
      }
    }
  }
}

Claude Code

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

Set your API key in the environment:

export CYCLES_API_KEY=cyc_live_...

Cursor / Windsurf

Use the stdio transport with:

command: npx
args: ["-y", "@runcycles/mcp-server"]
env: { CYCLES_API_KEY: "cyc_live_..." }

Mock mode (local development)

To try the server without a Cycles backend, enable mock mode. Mock mode returns realistic responses with deterministic data — no API key or running server needed.

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

Your first budget check

Once connected, ask your agent to check a budget balance:

"Check the budget balance for tenant acme-corp"

The agent will call cycles_check_balance with tenant: "acme-corp" and return balances for all scopes under that tenant — remaining budget, reserved amounts, and total spent.

The reserve/commit lifecycle

The core pattern is reserve → execute → commit. Here's how it works through MCP tools:

Step 1 — Reserve before doing something expensive:

"Reserve 500,000 USD_MICROCENTS for an OpenAI GPT-4o call"

The agent calls cycles_reserve and gets back a reservation_id and a decision. If the decision is ALLOW, the budget is locked and the agent can proceed.

Step 2 — Execute the operation (the LLM call, API request, etc.)

Step 3 — Commit the actual cost:

"Commit reservation res_abc123 with actual cost 423,100 USD_MICROCENTS"

The agent calls cycles_commit with the reservation_id and the actual amount. The difference between the reserved estimate and the actual cost is returned to the budget pool.

If the operation fails or is cancelled, the agent calls cycles_release instead to return the full reserved amount.

Handling decisions

When you call cycles_reserve or cycles_decide, the server returns one of three decisions:

Decision	Meaning	Agent should…
ALLOW	Budget is available, proceed normally	Execute the operation
ALLOW_WITH_CAPS	Budget is tight, proceed with constraints	Reduce scope — use a cheaper model, fewer tokens, or skip optional tools. The caps field contains maxTokens, toolAllowlist, and cooldownMs hints
DENY	Budget exhausted or insufficient	Stop, inform the user, or switch to a free fallback

Available tools

The MCP server exposes 9 tools:

Tool	Description
cycles_reserve	Reserve budget before a costly operation. Returns a reservation ID and decision
cycles_commit	Commit actual usage after an operation completes. Finalizes the charge
cycles_release	Release a reservation without committing. Returns budget to the pool
cycles_extend	Extend the TTL of an active reservation (heartbeat for long-running ops)
cycles_decide	Lightweight preflight check — ask if an action would be allowed without reserving
cycles_check_balance	Check current budget balance for a scope
cycles_list_reservations	List reservations, filtered by status or subject
cycles_get_reservation	Get details of a specific reservation by ID
cycles_create_event	Record usage directly without reserve/commit (fire-and-forget)

Built-in prompts

The server includes 3 prompts that agents can invoke for guided workflows:

Prompt	Description
integrate_cycles	Generate reserve/commit/release patterns for a specific language and use case
diagnose_overrun	Analyze budget exhaustion — guides through checking balances and listing reservations
design_budget_strategy	Recommend scope hierarchy, limits, units, and degradation strategy for a workflow

Configuration reference

Variable	Default	Description
CYCLES_API_KEY	(required)	API key for authenticating with the Cycles server
CYCLES_BASE_URL	https://api.runcycles.io	Base URL of the Cycles API
CYCLES_MOCK	—	Set to "true" to use mock mode (no server needed)
PORT	3000	HTTP port when using --transport http

Next steps

• Integrating Cycles with MCP — advanced patterns: preflight decisions, graceful degradation, long-running operations, fire-and-forget events
• Architecture Overview — how the MCP server fits into the full Cycles stack
• End-to-End Tutorial — walk through the complete reserve → commit lifecycle hands-on
• Cost Estimation Cheat Sheet — estimate token costs for popular LLM models