runcycles avatar

Cycles — Budget Authority for AI Agents

runcycles/cycles-mcp-server

Connects MCP-compatible agents (Claude Desktop, Cursor, Windsurf) to the Cycles budget authority API, giving agents runtime tools to reserve, commit, release, and check budget before expensive operations. You call cycles_reserve before an LLM invocation or tool run, cycles_commit to record actual spend, and cycles_decide to get policy decisions (allow, deny, degrade to cheaper model). The server enforces per-tenant or per-workspace spend caps without changing agent code. Use it when you need multi-tenant agents to self-regulate costs, prevent runaway spend in autonomous loops, or track usage across shared budgets. Ships with mock mode for local dev and prompts that help you design budget strategies.

tools
9
auth
Secret needed
transport
STDIO
env vars
9
last updated
Jul 27, 2026

Tools

9 tools

Public tool metadata for what this MCP can expose to an agent.

cycles_reserveReserve budget before a costly operation

Reserve budget before a costly operation

No parameter schema in public metadata yet.

cycles_commitCommit actual usage after operation completes

Commit actual usage after operation completes

No parameter schema in public metadata yet.

cycles_releaseRelease reservation without committing

Release reservation without committing

No parameter schema in public metadata yet.

cycles_extendExtend reservation TTL (heartbeat)

Extend reservation TTL (heartbeat)

No parameter schema in public metadata yet.

cycles_decideLightweight preflight budget check

Lightweight preflight budget check

No parameter schema in public metadata yet.

cycles_check_balanceCheck current budget balance for a scope

Check current budget balance for a scope

No parameter schema in public metadata yet.

cycles_list_reservationsList reservations with filters

List reservations with filters

No parameter schema in public metadata yet.

cycles_get_reservationGet reservation details by ID

Get reservation details by ID

No parameter schema in public metadata yet.

cycles_create_eventRecord usage without reserve/commit lifecycle

Record usage without reserve/commit lifecycle

No parameter schema in public metadata yet.

Sponsors

Configuration

CYCLES_API_KEY*secret

Cycles API key for authentication. Set CYCLES_MOCK=true for local development without a key.

CYCLES_BASE_URL*

URL of the Cycles server (e.g. https://api.runcycles.io). Required unless CYCLES_MOCK=true.

CYCLES_MOCKdefault: false

Enable mock mode for local development — no API key or live server required.

CYCLES_DEFAULT_TENANT

Optional default tenant merged into any tool call that omits it (explicit fields win).

CYCLES_DEFAULT_WORKSPACE

Optional default workspace merged into any tool call that omits it (explicit fields win).

CYCLES_DEFAULT_APP

Optional default app merged into any tool call that omits it (explicit fields win).

CYCLES_DEFAULT_WORKFLOW

Optional default workflow merged into any tool call that omits it (explicit fields win).

CYCLES_DEFAULT_AGENT

Optional default agent merged into any tool call that omits it (explicit fields win).

CYCLES_DEFAULT_TOOLSET

Optional default toolset merged into any tool call that omits it (explicit fields win).

Readme

npm npm Downloads CI License MCP Coverage SafeSkill 97/100

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


View the full README on GitHub

Details

Repository
github.com/runcycles/cycles-mcp-server
Website
runcycles.io
Package
@runcycles/mcp-server
Transport
STDIO
Auth
Required
Registry
MCP registry, active