Cycles MCP Server

Cycles MCP Server — Model Context Protocol を介した AI エージェントの実行時制御

**MCP サーバーは、あらゆる MCP 対応 AI エージェント（Claude Code、Cursor、Windsurf、カスタムエージェント）に、実行時の予算、アクション、監査の権限を与えます。エージェントのコードを変更せずに、実行前に LLM のコスト上限、ツール呼び出し上限、アクション権限、監査記録を適用できます。**MCP 経由で接続し、エージェントのツール呼び出しループから直接、予算ツール（cycles_reserve、cycles_commit、cycles_release、cycles_decide）を使用できます。Cycles を基盤としています。サーバー側で適用される内容と、エージェントループ内で協調的に適用される内容については、セキュリティモデルと適用境界をご覧ください。

これを使う理由

自律型 AI エージェント（Claude、GPT、カスタムエージェント）は LLM を呼び出し、ツールを実行し、外部 API を利用しますが、支出額を制限する組み込みの仕組みはありません。誰かが気付く前に、1 回のエージェントループで数百ドルを使い切ることもあります。これが複数のテナントやチームに及ぶと、コスト管理は深刻な問題になります。

この MCP サーバーは、あらゆる MCP 対応エージェントに実行時の予算管理権限を与えます。コストのかかる各操作の前後に、予算を確認、予約、使用、解放するためのツール一式を提供します。エージェントは操作の前に「これを実行する予算はあるか」と確認し、実行後に実際の使用量を報告します。

必要とするユーザー：

• プラットフォームチーム：顧客またはワークスペースごとの支出上限が必要な、マルチテナント型エージェントシステムを構築しているチーム
• エージェント開発者：エージェントに自律的な予算管理をさせたい開発者。予算が少なくなったら低コストのモデルに切り替え、任意のツール呼び出しを省略し、再試行を減らします
• 企業：エージェントの暴走による予算超過を防ぐガードレールが必要な、AI エージェントを導入している企業

MCP を使う理由：

MCP は、AI ホスト（Claude Desktop、Claude Code、Cursor、Windsurf、カスタムエージェント）がツールを検出して呼び出すための標準プロトコルです。Cycles を MCP サーバーとして公開することで、あらゆる MCP 対応エージェントがプラグインとして予算を認識できるようになります。設定にサーバーを追加するだけです。エージェント自身のコードに SDK を統合する必要はありません。

このサーバーには、AI アシスタントが予算戦略の設計、統合コードの生成、予算超過の診断を支援できる組み込みのプロンプトも用意されています。実行時に予算を適用するだけではありません。

ユースケース

タスクごとにドル上限を設けたコーディングエージェント

コードを作成し、反復的に改善する Claude Code エージェントを実行しているとします。各タスクのコストは 5 ドル以下に抑える必要があります。エージェントは、各 LLM 呼び出しの前にコストを USD_MICROCENTS で見積もって cycles_reserve を呼び出します。予約結果が DENY の場合、エージェントは停止し、請求額を気付かれないまま積み上げるのではなく、「予算を使い切りました」と報告します。呼び出しが完了すると、cycles_commit が実際のトークンコストを記録するため、累計額は正確に保たれます。

顧客ごとの予算を設定したマルチテナント SaaS

お客様が AI アシスタントをデプロイできるプラットフォームを運営しています。各お客様には月間予算があります。エージェントは会話の開始時に cycles_check_balance を呼び出して残りの予算を確認し、各ツールの呼び出し（ウェブ検索、コード実行、API 呼び出し）の前に cycles_reserve を呼び出します。顧客 Acme が上限に近づくと、判定として ALLOW_WITH_CAPS が返され、エージェントは自動的に低コストのモデルに切り替え、任意のツールをスキップします。顧客ごとの予算は分離されているため、ある顧客の大量利用が他の顧客に影響することはありません。

予算を共有するマルチエージェントパイプライン

研究担当、コーディング担当、レビュー担当の各エージェントにタスクを振り分けるオーケストレーターがあります。3 つのエージェントはすべて、同じワークフロー予算を使用します。各エージェントは作業の前に cycles_reserve を呼び出し、Cycles サーバーは同時に行われる予約を追跡して、合計がワークフローの上限を超えないようにします。研究担当エージェントが予算の 80% を使い切ると、コーディング担当エージェントの次の予約は DENY となり、オーケストレーターは予算超過を避けるためにレビューの手順をスキップできます。

ハートビートを使用した長時間実行データパイプライン

エージェントが大規模なデータセットをチャンクごとに処理し、各チャンクの処理に数分かかります。各チャンクの処理前に 5 分の TTL を指定して cycles_reserve を呼び出し、処理中は予約を維持するために 60 秒ごとに cycles_extend を呼び出します。エージェントがクラッシュすると予約は自動的に期限切れとなり、ロックされていた予算はプールに戻ります。手動でのクリーンアップは必要ありません。

呼び出し後に記録する使用量メーター

LLM 呼び出しをすでに行っている既存システムがあり、予算で制限するのではなく、支出を追跡したいだけの場合です。各呼び出しの完了後、エージェントは実際のコストを指定して 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=

エージェントの使いやすさに関する動作：明示的な対象フィールドは常に CYCLES_DEFAULT_* の値より優先され、デフォルトでフィルターが指定されている場合、cycles_check_balance は引数なしで呼び出せます。idempotencyKey はすべての状態変更ツールで引き続き必須です。同じキーでの再試行は、プロトコルにおける重複排除と証拠抑制の仕組みであり、再試行の間、キーを一定に保てるのは呼び出し元だけです。予算が逼迫している場合（DENY、ALLOW_WITH_CAPS、または残り約15％未満）、レスポンスにはJSONペイロードの後にプレーンテキストのヒントが含まれるため、ホストのサポートがなくてもエージェントは自ら動作を調整できます。

モックモードでは、起動のたびに目立つ警告が表示され、生成されるモックの予約IDとイベント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 キーが必要ですか？ API キーは Cycles Admin Server（ポート7979）から作成できます。デプロイガイドを参照して作成するか、次を実行してください。

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 キーは不要です。複数のユーザーまたはワークスペース向けにエージェントをデプロイする場合は、マルチテナント設定ガイドを参照してください。

実行

# 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	予約／確定のライフサイクルを経ずに使用量を記録する

エージェントの判断ループ

コストのかかる操作はすべて、予約 → 実行 → 確定のライフサイクルに従います。

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 の権限は2つの異なる境界で適用されます。どちらを頼りにしているかが重要です。

無条件で強制（サーバー側）

cycles_reserve、cycles_commit、cycles_decide の各呼び出しは、いずれも「権限の要求」であり、認証済みテナントのポリシーと現在の残高に基づいて Cycles ランタイムが評価します。これは、モデルが何を生成しても変わりません。

• 不正な金額が MCP サーバーの外に出ることはありません。 入力スキーマは、リクエストを行う前に、負の値、小数、数値以外の値、および JavaScript の安全な整数の上限（2⁵³ − 1）を超える値を拒否します。
• 形式は正しくても過剰な予約は Cycles サーバーによって拒否されます。 BUDGET_EXCEEDED エラーが返され、予約 ID は発行されず、何も消費されません。幻覚やプロンプトインジェクションによる過剰な予約によって、ポリシーで許可された以上の権限が Cycles から付与されることはありません。
• 予約だけでは何も消費されません。 予算が移動するのは cycles_commit（または cycles_create_event）の実行時のみで、コミット額は予約額と設定済みの超過ポリシーによって制限されます。

協調的（エージェントのツールループ内）

この MCP サーバーは、ホストのほかのツールと並んで予算ツールを公開します。モデルとそれらのツールの間に割り込むものではありません。予約が拒否された場合、エージェントには処理を続行しないよう指示されますが、MCP プロトコル自体がそれを強制するわけではありません。プロンプトインジェクションを受けたエージェントや、正常に動作しないエージェントは、cycles_reserve を完全に省略して、影響の大きいツールを直接呼び出す可能性があります。

バイパスできない強制を実現する

予算チェックを単なる慣例ではなく、厳格なゲートにするには、下流の操作が有効な予約なしで実行されないよう、実際のディスパッチ経路に Cycles を組み込みます。

• ホストアプリケーションでゲートする — 影響の大きい操作を実行する前に予約 ID を必須とし、cycles_get_reservation で検証します。
• ディスパッチ経路との統合を使用する — ツールの実行をラップするフレームワークのミドルウェア（例：Cycles Spring Boot starter や LangChain 統合）によって、モデルが省略できないコード内で、予約後に実行する順序を強制します。
• バックストップとしてサーバー側で計測する — ゲートを設けられない場合は、cycles_create_event で実際の使用量を記録し、少なくとも超過を検出して予算を正確に保ちます。

モックモードでは何も強制されません

CYCLES_MOCK=true の場合、すべての呼び出しは合成された ALLOW を返します。このモードは開発とデモ専用です。合成された ALLOW が実際の許可と誤認されないよう、NODE_ENV=production の場合、明示的に上書きしない限り、サーバーはモックモードでの起動を拒否します。

リソース

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

公開

このサーバーは、次の 2 つのレジストリに公開されています。

レジストリ	識別子	方法
npm	@runcycles/mcp-server	CI が v* タグのプッシュ時に、プロベナンス付きで公開します
MCP Registry	io.github.runcycles/cycles-mcp-server	npm の公開後、CI が server.json マニフェストを公開します

リリースは release-please で自動化されています。PR はスカッシュマージ（リポジトリではスカッシュのみを許可）され、Conventional PR タイトル（feat:、fix: など）が使用されます。PR タイトルは main 上の単一のコミットとなり、release-please が読み取ります。release-please は、変更履歴を蓄積し、package.json、server.json（両方のフィールド）、および AUDIT.md のヘッダーのバージョンを更新するリリース PR を管理します。リリース PR をマージすると、タグと GitHub リリースが作成され、その後、公開パイプラインが起動します。

CI はタグ上で次の処理を実行します：テスト（Node 20+22）→ npm 公開（Trusted Publishing/OIDC、プロベナンス付き）→ 公開された tarball に対するスモークテスト → MCP Registry への公開 → GitHub リリースに添付する MCPB デスクトップ拡張機能バンドル。

手動での代替手順（変更なしで機能します）：自分でバージョンを更新し、タグを付けてプッシュします。

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 に送信されることはありません。LLM のプロンプトや応答は保存されません。このサーバーには、テレメトリー、ホームへの通信、更新チェックはありません。モックモードでは、ネットワークリクエストは一切行われません。API キーはローカル設定に保存され、設定した Cycles サーバーにのみ送信されます。

ライセンス

Apache-2.0