Helio

Helio

MCP エージェントのためのオープンソースガバナンス：無制限の権限を与えずに、有用な自律性を実現します。

はじめに · ドキュメント · コントリビュート

---

Helio は、AI エージェントとそのエージェントが使うツールの間に入る MCP プロキシです。すべてのツール呼び出しは Helio を経由し、Helio はポリシーを適用し、前提条件を要求し、証拠を確認し、承認を振り分け、累積支出に上限を設け、すべてを記録します。エージェントのコードも MCP サーバーも変更する必要はありません。

2026-07-28 の MCP リビジョンでは、プロトコル自体がステートレスになりました。ハンドシェイクもプロトコルレベルのセッションもなく、呼び出しをまたぐ状態は、モデルがツール間で受け渡すハンドルとして保持されます。このパターンはアプリケーションの状態には有効ですが、ガバナンスの状態には適しません。モデルが参照できる予算キーは、モデルが変更できる予算キーだからです。Helio はセッション ID、予算、証拠をエージェントのコンテキストの外にあるプロキシで管理します。そのため、プロトコルがセッションの追跡をやめた後も、これらの制御は意味を保ちます。詳しくは、ステートレスなプロトコル、ステートフルなガバナンスをご覧ください。

npx @gethelio/proxy init

インストールする Node パッケージは @gethelio/proxy のみです。プロキシのランタイムと、バンドルされたダッシュボード UI アセットが一緒に含まれています。

ALLOW      read_customer
APPROVE    refund > £50
DENY       production.delete
BUDGET     £500/day across matching paid tools
REQUIRE    order.lookup succeeded before refund

Helio を選ぶ理由

エージェントが、想定していなかった API を呼び出しました。許可していない金額を使いました。簡単には元に戻せない本番環境のレコードを変更しました。

モデルプロバイダーは自社プラットフォーム向けのガバナンスを構築していますが、エージェントは Claude、ChatGPT、LangChain、CrewAI、独自のフレームワークをまたいで動作します。全体を統制できる単一のプラットフォームはありません。また、Stripe、Salesforce、GitHub などの下流システムで起きることを統制できるものもありません。

Helio は、あらゆる MCP 互換エージェント、あらゆるツール、あらゆるプラットフォームを通じて、エージェントが外の世界に対して行うことを統制します。

Helio のルールは、忘れられることも、密かに弱められることもありません。モデルのコンテキスト内にないため、長いセッションによって追い出されることも、インジェクションによって覆されることもありません。また、適用処理はプロンプト内ではなく処理経路上にあります。Helio 経由のツール呼び出しは、モデルに何が伝えられていようと、転送前に判断されます。ルールを削除するものも含め、ポリシーファイルの再読み込みはすべて監査記録となり、各記録には書き込み時に有効だった設定のハッシュが含まれるため、変更と、その設定のもとで下された判断を照合できます。「密かに弱められない」という主張には条件が一つあります。詳しくは適用レベルをご覧ください。

仕組み

統合方法は次の 2 つです。

1. プロキシのみ：MCP クライアントの接続先を MCP サーバーではなく Helio にします。コードの変更は不要です。すぐにガバナンスが適用されます。
2. プロキシ + SDK：軽量 Python SDK を追加して、証拠のコンテキストとアクションの依存関係をツール呼び出しに付与します。よりきめ細かなガバナンスを、500 行未満のコードで実現できます。

適用レベル

Helio は各経路で物理的に実現できる最も強いレベルでガバナンスを適用し、そのレベルを呼び出しごとに記録します。

• 構造レベル（stdio MCP）— Helio は自身が起動した子プロセスを所有するため、MCP 経路上で迂回されることはありません。同じコマンドラインを実行できる同一ホスト上のプロセスは、このレベルの対象外です（以下の注を参照してください）。
• ネットワークレベル（HTTP MCP）— アップストリームの外向き通信を制御できる場合は、構造レベルと同等です。
• ホスト適用レベル（アダプター API を介したフックアダプター。OpenClaw など）— ツールをプロセス内で実行し、MCP トランスポートではなくフックを公開するフレームワーク向けです。適用するのはフレームワークのフックゲートで、判断するのは Helio です。これはプロキシ経路よりも低い、協調的なレベルです。Helio は過大な主張をせず、その旨を明示します。Helio の判断がエージェントのコンテキストから削除されたり、プロンプトインジェクションによって書き換えられたりすることはなく、それらを迂回しようとする試みはすべて監査証跡に記録されます。

この 3 つのレベルはいずれも、プロキシの設定、シークレット、監査ストアがエージェントの手の届かない場所にあることを前提としています。デフォルトのローカルインストールでは、この前提を満たしません。プロキシはエージェントと同じユーザーで実行されます。SECURITY.md に、この境界と、それを確保するデプロイ方法が記載されています。また、「気付かれずに弱体化されない」という条件も、このインストール形態が前提です。同じユーザーで動作するエージェントは、設定の固定なしにプロキシを再起動したり、監査ファイルを編集または削除したりできます。そのため、エージェントが監査ファイルに書き込めない場合に限り、再読み込みの記録と各記録のハッシュが永続化されます。それ以前にボックスの外へ出るチャネルは、イベントストリームと stderr です。ここに記載されているレシピのとおり、プロキシを専用ユーザーまたは専用コンテナで実行すれば、この制約はなくなります。

クイックスタート（5 分）

1. インストール

npx @gethelio/proxy init

この単一のパッケージには、組み込みのダッシュボード UI バンドルが含まれています。

エージェントをコンテナ内で実行していますか？npx @gethelio/proxy init --sandbox を実行すると、代わりにサイドカー構成が書き込まれます。詳しくはHelio をサイドカーとして実行するを参照してください。

2. 設定する

npx @gethelio/proxy init を実行すると、プロジェクトのルートに helio.yaml が作成されます。このファイルを開き（例：nano helio.yaml、またはエディターで開く）、upstream.url を既存の MCP サーバーに設定します。単数形の upstream: 形式も引き続き完全にサポートされています。複数の MCP サーバーを管理するには、代わりに名前付きの upstreams: リストを宣言します（どちらか一方だけを設定してください）。ツールセットが統合されることはありません。名前付きの各アップストリームは、それぞれ独自の /mcp/<name> から提供されます。設定リファレンスを参照してください。

サーバーが公開している内容が分からない場合は、npx @gethelio/proxy scan --upstream http://localhost:8080/mcp を実行すると、すべてのツールと、サーバーがそのツールを破壊的とマークしているか、MCP のデフォルトのままにしているか、さらにルールで照合できる引数が表示されます。ルールを作成する前に確認でき、プロキシを起動する必要もありません。

ご注意 — Helio は監査専用モードで起動します。 init は policies セクションをコメントアウトした状態で作成するため、初期状態では Helio は default: allow かつルールはゼロで動作します。すべてのツール呼び出しを監査ログに記録しますが、何もブロックしません。適用を開始するには、policies のコメントを解除して編集するか、独自のルールを貼り付けてください。ルールの構文については、ポリシーガイドを参照してください。

以下のブロックは、ポリシー、予算、監査、ダッシュボードのシークレットを示す設定例です。init が書き込むファイルではありません。

version: '1'

upstream:
  url: 'http://localhost:8080/mcp' # Your existing MCP server
  transport: streamable-http # streamable-http (default), sse, or stdio

listen:
  port: 3000 # Helio listens here

session:
  identity: # Ordered identity sources; first match wins
    - source: header
      name: x-helio-session-id # Agent harnesses set this once per run
    - source: legacy_header # Verbatim Mcp-Session-Id (deprecation window)
  on_unresolved: deny # deny | anonymous

policies:
  default: allow

  # These rules match on tool-name globs (deny / rate-limit / spend-limit):
  rules:
    # Block destructive operations
    - match:
        tool: 'delete_*'
      action: deny
      feedback:
        message: 'Destructive operations are disabled'

    # Rate limit expensive API calls
    - match:
        tool: 'search_*'
      action: rate_limit
      limits:
        max_calls: 100
        window: 1h
        key: tool

    # Spend limit on payment tools
    - match:
        tool: 'create_payment'
      action: spend_limit
      limits:
        max_spend:
          field: '$.amount'
          limit: 5000
          currency: 'GBP'
          window: 24h

budgets:
  # One depleting pot shared by every tool that spends.
  - name: agent-payments
    limit: 50
    currency: USD
    window: session
    key: session
    on_exceed: deny # or require_approval for a break-glass ticket
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

audit:
  storage: sqlite
  retention: 90d
  include_responses: true

dashboard:
  enabled: true
  port: 3100
  api_secret: '${HELIO_DASHBOARD_SECRET}'

listen.host、dashboard.host、audit.path など、省略されたフィールドには安全なデフォルト値が適用されます（両方のホストには 127.0.0.1 — ループバックのみ —、パスには ./helio-audit.db）。設定リファレンスには、すべてのフィールドとそのデフォルト値、および正式なセクション順序が記載されています。

アップストリームで静的な認証情報（例：ホスト型 MCP サーバーでの Authorization: Bearer …）が必要な場合は、upstream.headersを設定してください。値では ${VAR} による補間がサポートされているため、シークレットをファイルに記載せずに済みます。

テスト対象の MCP サーバーがありませんか？Helio には、1 つのコマンドで実行できる依存関係ゼロのエコーサーバーが付属しています。スタートガイドを参照してください。

dashboard.api_secret について：

• npx @gethelio/proxy init を実行した場合、helio.yaml には生成されたシークレットの SHA-256 ダイジェストがすでに含まれており、init の実行時にシークレット自体が一度だけ表示されています。表示された値を保管してください。ログインに使用します。この手順はスキップしてください。

• ${HELIO_DASHBOARD_SECRET} プレースホルダーを使って helio.yaml を手動で作成した場合は、start の前に変数を設定してください。

  export HELIO_DASHBOARD_SECRET="$(openssl rand -hex 32)"
  

3. Helio を起動する

npx @gethelio/proxy start

4. エージェントの接続先を Helio にする

{
  "mcpServers": {
    "my-tools": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

エージェントをすぐに使えませんか？ Helio の動作を確認するのにエージェントは必要ありません。公式の MCP Inspector の接続先を http://localhost:3000/mcp に設定します（npx @modelcontextprotocol/inspector を実行し、トランスポートに Streamable HTTP を選択してください — Inspector は独自のローカルバックエンドを介して接続するため、Origin ヘッダーは送信されません。ブラウザーから送信された Origin は仕様上拒否されます）。または、ターミナルからプロキシ経由で直接呼び出します。

curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}'

どちらの場合も、ポリシーの判定結果とともにダッシュボードに呼び出しが表示されます。（get_weather は、Helio のエコーサーバーに含まれるデモ用ツールの 1 つです。）

5. ダッシュボードを開く

http://localhost:3100

プロンプトが表示された場合は、init が出力したダッシュボードシークレットでログインしてください（ファイルにはそのダイジェストのみが保存されています）。

これで完了です。以降、すべてのツール呼び出しは Helio を経由し、完全な監査証跡、レート制限、支出管理が適用されます。

書き込み操作に対して人間による承認を取り入れたい場合は、完全な Slack およびダッシュボードでの承認フローについて docs/approvals.md を参照するか、出発点として examples/slack-approvals/ をコピーしてください。

機能

ポリシーエンジン

ツール名、アノテーション、入力パラメーター、環境、累積状態に基づいて照合する、宣言型の YAML ルールです。取り消し不可能な操作にはフラグが付けられ、ドライランモードでは MCP サーバーに転送せずにパイプライン全体を実行します。ポリシーは再起動せずにホットリロードされます。

policies:
  rules:
    - match:
        tool: 'create_payment'
        input:
          '$.amount': { gt: 1000 }
      action: require_approval

複数アップストリームのガバナンス

1 つのプロキシで複数の MCP サーバーを管理できます。名前付きの upstreams: リストは単一の upstream: に代わるもので（設定にはどちらか一方のみを指定でき、両方を指定することはできません。単一形式も引き続きサポートされます）、名前付きの各アップストリームはそれぞれの /mcp/<name> および /sse/<name> のエンドポイントで提供され、ツールセットは統合されません。

エンドポイント間でガバナンスは統一されています。ルールで match.upstreams を指定できる 1 つのポリシーファイル、1 つの予算エンジン、1 つの承認キュー、1 つの監査証跡、1 つのダッシュボードを使用します。設定リファレンスの upstreams、ポリシーガイドの upstreams、および 複数アップストリームのサンプル を参照してください。

upstreams:
  - name: files
    url: 'http://localhost:8081/mcp'
  - name: payments
    url: 'http://localhost:8082/mcp'

ツール横断型の支出予算

ツールやサーバーをまたいで 1 つの予算を適用します。1 つの減額式の予算枠で、金額を含む引数フィールドがどれであるか、ツールがどの MCP サーバーの背後にあるかにかかわらず、その予算枠に紐づくすべてのツールの支出を合算します（Stripe と PayPal の支出を 1 つの上限にまとめます）。MCP ゲートで確定的に適用され、永続的な支出台帳によって再起動後も維持されます。上限超過時には緊急承認を利用でき、ダッシュボードでリアルタイムに確認できます。

budgets:
  - name: daily-cap
    limit: 50
    currency: USD
    window: 24h
    on_exceed: require_approval # a breach becomes a human decision
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

予算は、引数フィールドで支出額を公開するツールに適用されます。支出のリアルタイムな減額、超過、緊急承認、承認された超過分の台帳への記録まで、一連の流れを Docker クイックスタートデモ または実行可能な 予算のサンプル で確認できます。

エビデンスによる根拠付け

アプリケーションから提供される新しいエビデンスを必須にします。オプションの SDK はセッションのエビデンスキーを送信します。プロキシは、そのキーがポリシーの許可リストにあり、存在し、有効期限が切れていないことを確認します（呼び出し元は各エントリーの TTL を設定し、SDK のデフォルトは 300 秒です）。Helio が検証するのはエビデンスシグナルの存在と鮮度であり、その内容ではありません。また、SDK トークンはエージェントのプロセス内にあるため、エビデンスゲートは、意図的にスキップしようとするエージェントへの対策ではなく、手順の誤ったスキップを防ぐものとして扱ってください。SECURITY.md を参照してください。

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: allow
      evidence:
        requires: ['orders.lookup']

# Optional SDK enrichment
from helio import HelioContext

# Mark a tool output as evidence
with HelioContext() as ctx:
    result = orders.lookup(order_id)
    ctx.mark_evidence("orders.lookup", "order_data", result)

SDK はサイドバンド API 経由でプロキシと通信します（デフォルトは 127.0.0.1:3200、バインドホストは sdk.host で設定可能です）。SDK のサイドバンドが有効な場合（sdk.enabled: true。デフォルトでは無効）、プロキシは helio start のたびに新しい 32 バイトの 16 進数トークンを生成し、標準エラー出力に表示します。

SDK sideband listening on http://127.0.0.1:3200
SDK token (generated per-boot HELIO_SDK_TOKEN; pass as HELIO_SDK_TOKEN env var to your SDK clients):
  3f9c2b...d8a1

同じ値を HELIO_SDK_TOKEN 経由で SDK のプロセスに渡すと、SDK はすべてのサイドバンド呼び出しに Authorization: Bearer <token> を自動的に付加します。また、サイドバンドは Origin ヘッダーが null 以外のリクエストを拒否するため、悪意のあるローカル HTML ファイルがブラウザー経由でサイドバンドに接続することはできません。再起動後も同じトークンを使う必要がある運用者は、プロキシの環境変数に HELIO_SDK_TOKEN を明示的に設定できます。プロキシは値が事前に設定されている場合は再生成せず、その値を尊重し、標準エラー出力にも表示しません。

自己修復フィードバック

Helio はアクションをブロックすると、何が失敗したか、エージェントが次に何をすべきかを説明する構造化フィードバックを返します。エージェントはそれを受けて自ら修正し、再試行できます。

{
  "blocked": true,
  "reason": "evidence_missing",
  "missing_evidence": ["orders.lookup"],
  "suggestion": "Call orders.lookup with the order ID before retrying"
}

アクションの依存関係チェーン

前提となるアクションの成功を必須にします。このセッションですでに orders.lookup が成功している場合を除き、返金はできません。プロキシは呼び出し自体を監視します。デフォルトでは、エラーではなく上流からの結果を返したルーティング済みツール呼び出しによってのみ、依存関係が満たされたと見なされます。あらゆる試行を対象にするには、requires_success: false を設定してください。

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: allow
      requires: ['orders.lookup', 'customer.verify']

承認ワークフロー

承認が必要なものだけをエスカレーションし、承認者に引数を提示します。機密性の高い呼び出しを Slack、Webhook、または Helio ダッシュボードにルーティングできます。チケットにはツール、上流、適用されたルール、呼び出しの引数が含まれ、人間が判断するまで呼び出しは実行されません。タイムアウトとエスカレーションを設定でき、緊急時の上書きはダッシュボードのみで利用できます（REST API とダッシュボード UI で利用可能。Slack のボタンとしては公開されていません）。

レート制限と利用額の上限

ツールごと、およびセッションごとにレート制限を設定できます。ルールごとの利用額上限に達すると、一致したツールをブロックします。複数のツールにまたがる累積上限については、ツール横断の利用額予算を参照してください。

監査証跡

すべてのツール呼び出しを記録します。記録項目は、タイムスタンプ、エージェントの識別情報、ツール名、入力、ポリシーの判断、エビデンスチェーン、承認状況、下流からの応答、レイテンシ、および記録の書き込み時に適用されていた設定のハッシュです。ダッシュボードから検索でき、JSON または CSV にエクスポートできます。

Helioとの比較

	Helio	Obot	Cerbos	組み込み（Anthropic / OpenAI）	フレームワーク（LangChain / CrewAI）
ガバナンスの対象	呼び出しをまたぐ状態を含む、呼び出しごとのアクション	到達可能なツール/MCP	アプリレベルの認可判断	1つのプラットフォーム内のエージェント権限	1つのフレームワーク内のエージェント動作
アーキテクチャ	プロセス外のMCPプロキシ	プロセス外のMCPゲートウェイ	サイドカー / ライブラリ	プラットフォーム内	フレームワーク内
オープンソース	✅ Apache 2.0	✅ Apache 2.0	✅ Apache 2.0	❌	さまざま
導入効果が得られるまでの時間	5分	セットアップに依存	数時間	組み込み	組み込み
エージェントのコード変更不要	✅	✅	❌	✅（プラットフォーム内）	❌
自分で構築していないエージェントのガバナンス	✅ あらゆるMCPエージェント	✅ あらゆるMCPエージェント	✅（あらゆるアプリ）	❌ 1つのプラットフォームのみ	❌ 1つのフレームワークのみ
根拠に基づく判定	✅ 呼び出しをまたいで累積	❌	❌	❌	限定的
自己修復フィードバック	✅ 構造化された再試行ヒント	❌	❌	❌	限定的
状態を保持する支出 / レート制限	✅ ツール横断の予算 + ルールごとの制限¹	基本的	❌	❌	限定的
承認ワークフロー	✅ Slack、Webhook、ダッシュボード	✅	❌	限定的	限定的
監査証跡（下流の応答を含む）	✅ 上流のMCP応答を記録	判断ログ	判断ログ	プラットフォームのテレメトリ	フレームワークのログ

¹ ルールごとのレート制限と支出制限に加え、名前付きのツール横断予算を利用できます。これらは継続的に残高が減る予算で、超過時には緊急承認を利用できます。

対応環境

Helioは、MCP互換のあらゆるエージェントやフレームワークで動作します。

• Claude（Anthropic）
• ChatGPT（OpenAI）
• LangChain / LangGraph
• CrewAI
• AutoGen
• 任意のMCPクライアントSDKを使用するカスタムエージェント

ドキュメント

完全版のドキュメントはモノレポにあり、このパッケージの tarball には含まれていません。

• はじめに：5 分でインストールと設定を行えます
• 設定リファレンス：すべての YAML オプションを解説します
• ポリシーガイド：例を交えてルールの作成方法を説明します
• アップストリームのスキャン：helio scan は、プロキシの実行前に、ヒントの出所、カバレッジ、引数の候補とともに、MCP サーバーが実際に提供するツール一覧を出力します
• 承認ワークフロー：Slack、Webhook、ダッシュボードでの承認
• 監査証跡：記録される内容、検索方法、エクスポート方法
• サイドカーとして Helio を実行する：アップストリームと設定に手が届かず、Helio がネットワークに接続されていない状態で、コーディングエージェントまたは開発コンテナの隣にデプロイします
• 専用ユーザーとして Helio を実行する：Ubuntu 24.04 での専用ユーザー層を、最初から最後まで実行します

例

一般的なパターン向けのすぐに使える設定：

• 基本：破壊的な操作を拒否し、それ以外はすべて許可します
• Slack 承認：破壊的なアクションを Slack に転送します
• 支出上限：決済ツールの使用を管理します
• 予算：Stripe と PayPal のツールをまたぐ予算に、緊急時の超過承認を組み合わせます。さらに、支出カテゴリを申告した呼び出しだけに課金するカテゴリ上限も設定します
• マルチアップストリーム：1 つのプロキシの背後に名前付きアップストリームを 2 つ配置し、ドア単位のレート制限と予算を設定します

コントリビュート

コントリビュートを歓迎します。セットアップ手順、コーディング規約、PR の手順については、CONTRIBUTING.md をご覧ください。

初めての方に適した Issue には good-first-issue ラベルが付いています。

コミュニティ

• GitHub Issues：バグ報告と機能リクエスト
• Twitter/X：更新情報とお知らせ

ライセンス

Apache 2.0 - LICENSE をご覧ください。