Cycles MCP Server — AI agent runtime control over Model Context Protocol

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 by Cycles. See Security Model & Enforcement Boundary for what is enforced server-side versus cooperatively in the agent loop.

Why use this?

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 a runtime 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.

Who needs this:

• Platform teams building multi-tenant agent systems that need per-customer or per-workspace spend limits
• Agent developers who want agents to self-regulate — degrade to cheaper models when budget is low, skip optional tool calls, reduce retries
• Enterprises deploying AI agents that need guardrails so a runaway agent can't blow through a budget

Why MCP specifically:

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-in prompts so an AI assistant can help you design your budget strategy, generate integration code, and diagnose budget overruns — not just enforce budgets at runtime.

Use Cases

Coding agent with a per-task dollar cap

You run a Claude Code agent that writes and iterates on code. Each task should cost no more than $5. The agent calls cycles_reserve before every LLM call with a cost estimate in USD_MICROCENTS. If the reservation comes back DENY, the agent stops and reports "budget exhausted" instead of silently racking up charges. When the call completes, cycles_commit records 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 calls cycles_check_balance at the start of a conversation to see what's left, then cycles_reserve before each tool invocation (web search, code execution, API calls). If customer Acme is near their limit, the decision comes back ALLOW_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.

Multi-agent pipeline with shared budget

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 calls cycles_reserve before 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 gets DENY and 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 calls cycles_reserve with a 5-minute TTL before each chunk, then cycles_extend every 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.

Fire-and-forget usage metering

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 fires cycles_create_event with 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.

Grok Bot with a non-bypassable paid-media action

Grok Bot can call custom MCP tools, but installing the standalone Cycles tools beside a paid-media connector remains cooperative: the Bot could call the other connector directly. The Grok Bot paid-media gateway shows the hard-enforcement shape instead. Its mutation handler derives scope from trusted server configuration, requires a live RISK_POINTS reservation, propagates the reservation ID to the downstream API, and conservatively settles ambiguous outcomes.

Installation

npm install @runcycles/mcp-server

Setup

Claude Desktop

One-click (recommended): download cycles-mcp-server-<version>.mcpb from the latest release and 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 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_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 Code

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

Set your environment variables:

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

Cursor / Windsurf / Other MCP Hosts

Use stdio transport with:

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

Configuration

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 over CYCLES_DEFAULT_* values, and cycles_check_balance accepts an empty call when defaults supply a filter. idempotencyKey remains required 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 with mock_. The server refuses to start with CYCLES_MOCK=true and NODE_ENV=production unless CYCLES_ALLOW_MOCK_IN_PRODUCTION=true is also set.

For HTTP transport, set MCP_HTTP_AUTH_TOKEN to require Authorization: Bearer <token> on every /mcp request. Blank or whitespace-only configured tokens are rejected at startup. /health remains 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 the deployment guide to 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, see API Key Management.

Individual vs. team use: For individual use or evaluation, set CYCLES_MOCK=true — no server or API key required. If you're deploying agents for multiple users or workspaces, see the multi-tenant setup guide.

Running

# 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

Tools

Agent Decision Loop

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

Optionally, before reserving:

• cycles_check_balance — inspect remaining budget to plan your approach
• cycles_decide — lightweight preflight check without locking funds

Every reservation must be finalized with either cycles_commit or cycles_release — never leave reservations dangling. For long-running operations, use cycles_extend to heartbeat the reservation TTL so it doesn't expire mid-operation. See integration patterns for detailed examples.

Security Model & Enforcement Boundary

Cycles authority is enforced at two different boundaries, and it matters which one you are relying on.

Enforced unconditionally (server-side)

Every cycles_reserve, cycles_commit, and cycles_decide call is a request for authority, evaluated by the Cycles runtime against the authenticated tenant's policies and current balances. This holds regardless of what the model generates:

• Malformed amounts never leave the MCP server. Input schemas reject negative, fractional, or non-numeric amounts, and any value above JavaScript's safe-integer range (2⁵³ − 1), before a request is made.
• A well-formed but excessive reservation is refused by the Cycles server with a BUDGET_EXCEEDED error — no reservation ID is issued and nothing is spent. A hallucinated or prompt-injected oversized reserve cannot make Cycles grant more authority than policy allows.
• A reservation by itself spends nothing. Budget only moves on cycles_commit (or cycles_create_event), and commits are bounded by the reservation plus the configured overage policy.

Cooperative (inside the agent's tool loop)

This MCP server exposes budget tools alongside the 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 skip cycles_reserve entirely and invoke a consequential tool directly.

Making enforcement non-bypassable

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 with cycles_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 with cycles_create_event so overruns are at least detected and budgets stay accurate.

Mock mode enforces nothing

With CYCLES_MOCK=true, every call returns a synthetic ALLOW — it exists for development and demos only. The server refuses to start in mock mode when NODE_ENV=production (unless explicitly overridden) precisely so a synthetic ALLOW is never mistaken for a real one.

Resources

Prompts

Development

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

Publishing

The server is published to two registries:

Releases are automated with release-please. PRs are squash-merged (repo enforces squash-only) with conventional PR titles (feat:, fix:, …) — the PR title becomes the single commit on main that release-please reads. It maintains a release PR that accumulates the changelog and bumps the version in package.json, server.json (both fields), and the AUDIT.md header. Merging the release PR creates 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:

git tag v0.5.0
git push origin v0.5.0

Documentation

• Cycles Documentation — full docs site
• MCP Server Quickstart — getting started guide
• Integrating Cycles with MCP — detailed MCP integration guide

Protocol Conformance

This MCP server is audited against the Cycles Protocol v0.1.24 OpenAPI spec. See AUDIT.md for the full conformance report.

Privacy Policy

Full policy: runcycles.io/privacy

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.

License

Apache-2.0