Cycles MCP Server

Cycles MCP Server — 通过 Model Context Protocol 控制 AI Agent 的运行时

MCP 服务可让任何兼容 MCP 的 AI Agent（Claude Code、Cursor、Windsurf、自定义 Agent）获得运行时预算、操作和审计权限——在执行前强制实施大模型成本限额、工具调用上限、操作权限和审计跟踪，且无需修改 Agent 代码。 通过 MCP 连接，并可直接在 Agent 的工具调用循环中使用预算工具（cycles_reserve、cycles_commit、cycles_release、cycles_decide）。由 Cycles 提供支持。有关服务端强制执行与 Agent 循环中协作执行的区别，请参阅安全模型与强制执行边界。

为什么要使用它？

自主 AI Agent（Claude、GPT、自定义 Agent）会调用大模型、使用工具并访问外部 API，但没有内置的支出限额机制。一个 Agent 循环就可能在无人察觉前花掉数百美元。如果这种情况发生在多个租户和团队中，成本控制就会成为实际问题。

此 MCP 服务为任何兼容 MCP 的 Agent 提供运行时预算权限：一组工具，可在每项高成本操作前后检查、预留、支出和释放预算。Agent 会在执行前询问“预算够吗？”，并在执行后报告实际用量。

适用对象：

• 平台团队：构建多租户 Agent 系统，需要按客户或工作区设置支出限额
• Agent 开发者：希望 Agent 自我调节——预算不足时改用更便宜的模型、跳过可选工具调用、减少重试
• 企业：部署 AI Agent，并需要设置防护措施，避免失控的 Agent 超出预算

为什么选择 MCP：

MCP 是 AI 主机（Claude Desktop、Claude Code、Cursor、Windsurf、自定义 Agent）用于发现和调用工具的标准协议。通过将 Cycles 作为 MCP 服务公开，任何兼容 MCP 的 Agent 都能通过插件获得预算感知能力——只需将此服务添加到配置中。无需在 Agent 自身代码中集成 SDK。

此服务还内置了提示词，AI 助手可借此帮助你设计预算策略、生成集成代码并诊断预算超支问题，而不仅仅是在运行时强制执行预算。

使用场景

设置单任务美元上限的编码 Agent

你运行一个用于编写和迭代代码的 Claude Code Agent。每项任务的成本不得超过 5 美元。每次调用大模型前，Agent 都会使用 USD_MICROCENTS 中的成本估算调用 cycles_reserve。如果预留结果为 DENY，Agent 就会停止并报告“预算已用尽”，而不是在无人察觉的情况下不断产生费用。调用完成后，cycles_commit 会记录实际的令牌成本，从而确保累计总额准确。

面向每位客户单独设定预算的多租户 SaaS

你的平台允许客户部署 AI 助手。每位客户都有月度预算。对话开始时，Agent 会调用 cycles_check_balance 查看剩余预算，然后在每次调用工具（网页搜索、代码执行、API 调用）之前调用 cycles_reserve。如果 Acme 客户接近预算上限，系统会返回 ALLOW_WITH_CAPS——Agent 会自动改用成本更低的模型，并跳过可选工具。客户的预算彼此隔离；一位客户的大量使用绝不会影响其他客户。

共享预算的多 Agent 工作流

你有一个编排器，可将任务分发给多个专业 Agent——研究员、编码 Agent 和审查员。三者共用同一工作流预算。每个 Agent 都会在开始工作前调用 cycles_reserve；Cycles 服务会跟踪并发预留，确保总额不会超过工作流限额。如果研究员用掉了 80% 的预算，编码 Agent 的下一次预留就会收到 DENY，编排器可以决定跳过审查步骤，而不是超出预算。

带心跳的长时间运行数据工作流

Agent 会分块处理大型数据集，每个数据块都需要数分钟。它会在处理每个数据块之前调用 cycles_reserve，并设置 5 分钟 TTL，然后每隔 60 秒调用 cycles_extend，以便在处理期间保持预留有效。如果 Agent 崩溃，预留会自动过期，锁定的预算也会返回预算池——无需手动清理。

即发即忘的用量计量

你有一个现有系统，已经在进行大模型调用，现在只想追踪支出，而不是限制调用。每次调用完成后，Agent 都会调用 cycles_create_event，并传入实际成本。无需预留——事件会以原子方式应用到所有预算范围（租户、工作区、应用）。无需更改现有调用流程，即可获得实时支出仪表板。

带有不可绕过的付费媒体操作的 Grok Bot

Grok Bot 可以调用自定义 MCP 工具，但在付费媒体连接器旁安装独立的 Cycles 工具仍依赖协作：Bot 可以直接调用另一个连接器。Grok Bot 付费媒体网关展示了如何实现强制执行。它的变更处理程序会根据可信的服务端配置确定范围，要求存在有效的 RISK_POINTS 预留，将预留 ID 传递给下游 API，并以保守方式结算结果不明确的操作。

安装

npm install @runcycles/mcp-server

设置

Claude Desktop

一键安装（推荐）： 从最新版本下载 cycles-mcp-server-<version>.mcpb，然后用 Claude Desktop 打开（双击，或进入 Settings → Extensions → 将文件拖入其中）。Claude Desktop 会显示配置界面，让你填写 Cycles 服务 URL 和 API 密钥；也可以启用模拟模式，在没有服务的情况下探索这些工具（不执行强制限制）。

手动安装（JSON 配置）： 将以下内容添加到 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"
      }
    }
  }
}

在本地开发时，如果没有 API 密钥，请使用模拟模式：

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

Claude Code

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

设置环境变量：

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

Cursor / Windsurf / 其他 MCP 宿主

使用 stdio 传输方式：

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 易用性行为：明确指定的主体字段始终优先于 CYCLES_DEFAULT_* 值；如果默认值提供了筛选条件，cycles_check_balance 可以接受空调用。每个变更类工具都必须提供 idempotencyKey——使用相同的键重放请求是协议层的重试去重和证据抑制机制，而且只有调用方能在重试期间保持键不变。当预算吃紧（DENY、ALLOW_WITH_CAPS 或剩余预算低于约 15%）时，响应会在 JSON 负载后附带纯文本提示，让 Agent 无需主机支持也能自我调节。

Mock 模式每次启动时都会打印醒目的警告，生成的 mock 预留和事件 ID 以 mock_ 开头。如果设置了 CYCLES_MOCK=true 和 NODE_ENV=production，但未同时设置 CYCLES_ALLOW_MOCK_IN_PRODUCTION=true，服务器将拒绝启动。

对于 HTTP 传输，设置 MCP_HTTP_AUTH_TOKEN，即可要求每个 /mcp 请求都携带 Authorization: Bearer <token>。配置的令牌为空或仅含空白字符时，服务器会拒绝启动。/health 仍然公开可访问。如果未配置令牌，而 HTTP 绑定到非环回地址，服务器会打印醒目的警告。

需要 API 密钥？ 请通过 Cycles Admin Server（端口 7979）创建 API 密钥。参阅部署指南以创建密钥，或运行：

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'

密钥（例如 cyc_live_abc123...）只会显示一次——请立即保存。有关密钥轮换和生命周期的详细信息，请参阅 API 密钥管理。

个人使用与团队使用： 如果是个人使用或评估，请设置 CYCLES_MOCK=true——无需服务器或 API 密钥。如果要为多个用户或工作区部署 Agent，请参阅多租户设置指南。

运行

# 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

工具

工具	协议端点	描述
cycles_reserve	POST /v1/reservations	在执行高成本操作前预留预算
cycles_commit	POST /v1/reservations/{id}/commit	操作完成后提交实际用量
cycles_release	POST /v1/reservations/{id}/release	释放预留，不提交用量
cycles_extend	POST /v1/reservations/{id}/extend	延长预留 TTL（心跳）
cycles_decide	POST /v1/decide	轻量级预算预检
cycles_check_balance	GET /v1/balances	检查某个范围的当前预算余额
cycles_list_reservations	GET /v1/reservations	按筛选条件列出预留
cycles_get_reservation	GET /v1/reservations/{id}	按 ID 获取预留详情
cycles_create_event	POST /v1/events	记录用量，无需预留/提交生命周期

Agent 决策循环

每项高成本操作都遵循预留 → 执行 → 完成的生命周期：

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 — 查看剩余预算，以规划处理方式
• cycles_decide — 进行轻量级预检，不锁定资金

每项预留都必须通过 cycles_commit 或 cycles_release 完成——切勿让预留处于未完成状态。对于长时间运行的操作，请使用 cycles_extend 发送心跳以延长预留 TTL，避免预留在操作期间过期。详细示例请参阅集成模式。

安全模型与强制执行边界

Cycles 的授权在两个不同边界上强制执行；明确你所依赖的边界很重要。

无条件强制执行（服务端）

每次调用 cycles_reserve、cycles_commit 和 cycles_decide 都是权限申请，由 Cycles 运行时根据经过身份验证的租户策略和当前余额进行评估。无论模型生成什么内容，这一规则都适用：

• 格式错误的金额绝不会离开 MCP 服务。 输入架构会在发出请求前拒绝负数、小数、非数字金额，以及任何超出 JavaScript 安全整数范围（2⁵³ − 1）的值。
• 格式正确但超出限额的预留会被 Cycles 服务拒绝，并返回 BUDGET_EXCEEDED 错误——不会签发预留 ID，也不会产生任何支出。无论是模型幻觉还是提示词注入，都无法让 Cycles 授予超出策略允许范围的权限。
• 预留本身不会产生支出。 预算只会在调用 cycles_commit（或 cycles_create_event）时变动，且提交金额受预留额度和配置的超额策略限制。

协作式执行（在 Agent 的工具循环中）

此 MCP 服务与宿主提供的其他工具并列，而不是位于模型与这些工具之间。预留遭拒时，系统会指示 Agent 不要继续，但 MCP 协议中没有任何机制强制执行这一指示。遭到提示词注入或行为不当的 Agent 可能会完全跳过 cycles_reserve，直接调用会产生实际影响的工具。

实现不可绕过的强制检查

若要让预算检查成为硬性关卡，而非约定俗成的规则，就应将 Cycles 放入实际的分发路径中，确保下游操作无法在没有有效预留的情况下执行：

• 在宿主应用中设置关卡——执行会产生实际影响的操作前，要求提供预留 ID，并通过 cycles_get_reservation 验证。
• 使用分发路径集成——通过封装工具执行的框架中间件（例如 Cycles Spring Boot starter 或 LangChain 集成）在代码中强制执行先预留后执行，模型无法跳过这一检查。
• 在服务端进行用量计量，作为后备措施——如果无法设置关卡，就使用 cycles_create_event 记录实际用量，至少可以检测超额使用并确保预算准确。

模拟模式不执行任何强制检查

启用 CYCLES_MOCK=true 后，每次调用都会返回合成的 ALLOW——此模式仅供开发和演示使用。服务器在 NODE_ENV=production 时拒绝以模拟模式启动（除非明确覆盖），正是为了避免将合成的 ALLOW 误认为真实结果。

资源

URI	说明
cycles://balances/{tenant}	租户的当前预算余额
cycles://reservations/{reservation_id}	预留详情
cycles://docs/quickstart	入门指南
cycles://docs/patterns	集成模式

提示词

提示词	说明
integrate_cycles	生成 Cycles 集成代码
diagnose_overrun	分析预算耗尽情况
design_budget_strategy	推荐范围层级和限额

开发

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

发布

该服务发布到两个注册表：

注册表	标识符	方式
npm	@runcycles/mcp-server	CI 在推送 v* 标签时发布，并附带来源证明
MCP Registry	io.github.runcycles/cycles-mcp-server	npm 发布后，CI 发布 server.json 清单

发布流程由 release-please 自动执行。PR 会进行压缩合并（仓库强制仅允许压缩合并），并使用约定式 PR 标题（feat:、fix: 等）——PR 标题会成为 main 上的唯一提交，供 release-please 读取。它会维护一个发布 PR，用于累积变更日志，并更新 package.json、server.json（两个字段）以及 AUDIT.md 标题中的版本号。合并发布 PR 会创建标签和 GitHub 发布版本，然后触发发布流水线。

CI 会在标签上运行：测试（Node 20+22）→ npm 发布（Trusted Publishing/OIDC，附带来源证明）→ 使用已发布的 tarball 进行冒烟测试 → 发布到 MCP Registry → 将 MCPB 桌面扩展包附加到 GitHub 发布版本。

手动备用流程（无需更改）：自行更新版本号，然后创建并推送标签：

git tag v0.5.0
git push origin v0.5.0

文档

• Cycles 文档 — 完整文档网站
• MCP 服务快速入门 — 入门指南
• 将 Cycles 与 MCP 集成 — 详细的 MCP 集成指南

协议符合性

此 MCP 服务已根据 Cycles Protocol v0.1.24 OpenAPI 规范完成审计。完整的符合性报告请参阅 AUDIT.md。

隐私政策

完整政策：runcycles.io/privacy

简而言之：此服务仅连接到你配置的 Cycles 服务 URL，并向其发送预算请求（主体标识符、金额、使用指标）——Cycles 可自托管，因此这些数据会保留在你的基础设施中，不会传到 runcycles。不会存储任何大模型提示词或回复。此服务不包含遥测、回传或更新检查功能。在模拟模式下，不会发出任何网络请求。你的 API 密钥保存在本地配置中，只会发送到你配置的 Cycles 服务。

许可证

Apache-2.0