Unified AI System MCP Gateway

Unified AI System MCP サーバー

Codex およびその他の MCP ホストを、認証情報不要の Unified AI System プレビューに stdio または MCP Streamable HTTP で接続します。

サーバーは分離されたローカルゲートウェイを自動的に起動し、決定論的な 偽プロバイダーに固定します。認証済みで権限がスコープされたツールを公開し、 MCP セッション終了時にゲートウェイを削除します。実際のプロバイダー呼び出しを 有効化したり、許可したりすることはありません。

ツール

ツール	動作
gateway_health	ゲートウェイの健全性とプロバイダーの安全状態を確認します。
gateway_readiness	初回起動時とチャットの準備状況を確認します。
agent_governance_status	認証済み ID にプラットフォームステータスへのアクセス権がある場合、Agent Governance の状態を確認します。
agent_governance_list	認証済みテナントから参照可能な、ガバナンス対象の Agent のみを一覧表示します。
agent_governance_describe	認証済みテナントに属する場合に限り、1 つの Agent の詳細を表示します。
gateway_prompt_enhance	プロバイダーを呼び出さずに、自然言語のリクエストをローカルで構造化します。
gateway_prompt_enhance_llm	オプションの LLM バックエンドを介してプロンプトを強化します（利用できない場合は代替処理に切り替わります）。
gateway_chat	偽プロバイダー専用のチャットリクエストを 1 件送信します。
knowledge_readiness	ローカルのナレッジ基盤の準備状況を確認します。
knowledge_retrieve	キーワードでローカルのナレッジベースを検索します。
workflow_health	ガバナンス対象のワークフローサブシステムの状態を確認します。
workflow_actions	ワークフローアクションの定義を一覧表示します。
workflow_run	3 ステップのローカルワークフローを実行し、テナントごとに分割されたアーティファクトをアトミックに公開します。マネージドモードでは専用の file_write Agent を注入します。外部のガバナンス対象ゲートウェイでは agentId が必要です。
workforce_health	ワークフォースサブシステムの状態を確認します。
workforce_agents	ワークフォースエージェントの記述子を一覧表示します。

Agent Governance の確認ツールは読み取り専用です。workflow_run は管理されたローカルアーティファクトを 1 つ書き込みます。MCP ツールプロトコルでは、トランスポートのタイムアウト後に冪等性があり、キャンセル安全性を備えた生成をまだ証明できないため、Agent の作成は REST、共有 SDK、人間が操作する Agent Console の各インターフェイスから引き続き利用できます。MCP ツールでは、Agent の作成・実行・取り消し、承認・却下、ポリシーの作成・有効化はできません。ガバナンスツールは tenantId や ownerUserId を受け取りません。ゲートウェイは認証済み ID からその両方を設定し、テナントをまたぐ詳細表示は「見つからない」として失敗します。workflow_run が既存のパスを上書きすることはなく、接続先のゲートウェイでそのコントロールプレーンが有効になっている場合は、Agent Governance を経由してルーティングされます。チャットツールはリクエストごとにゲートウェイの安全状態を確認し、realProviderEnabled が正確に false であり、かつレスポンスが executionMode: "fake" を証明しない限り、フェイルクローズします。

ソースからのビルドでは、4 つの Agent Governance ライフサイクルツールと、プロバイダーを使わない gateway_prompt_enhance プレビューを含む 16 個のツールが公開されます。公開済みイメージでは、固定されたタグに含まれるツールセットが公開されます。

ソースから実行する

リポジトリのルートから実行します。

pnpm install --frozen-lockfile
node packages/mcp-server/src/index.js

プロジェクトレベルの .codex/config.toml によって、信頼済みの Codex プロジェクトではこのコマンドが自動的に登録されます。MCP の設定を複製または変更した後は Codex を再起動し、/mcp を使ってサーバーを確認してください。

Streamable HTTP

ソースビルド版の HTTP トランスポートを起動します。

pnpm mcp:http

MCP エンドポイントは http://127.0.0.1:3210/mcp です。デフォルトではループバックでリッスンし、Host と Origin を検証して、同じフェイクプロバイダーゲートウェイを起動し、stdio と同じ 16 個のソースビルド版ツールを公開します。任意の MCP Streamable HTTP クライアントをこの URL に接続してください。

ローカルのトークン保護されたエンドポイントを使用するには、MCP_HTTP_AUTH_TOKEN を設定し、Authorization: Bearer <token> として送信します。ループバック以外へのバインドは、次のすべての変数が設定されていない限り、フェイルクローズします。

変数	要件
MCP_HTTP_HOST	0.0.0.0 などの、ループバック以外のバインドアドレス。
MCP_HTTP_AUTH_TOKEN	32 バイト以上であること。ソース管理に含めないでください。
MCP_HTTP_ALLOWED_HOSTS	ポートを含まない、カンマ区切りのリクエストホスト名。
MCP_HTTP_ALLOWED_ORIGINS	スキームやポートを含まない、カンマ区切りのブラウザーオリジンホスト名。

TLS リバースプロキシの背後にあるプライベート環境へのデプロイ例：

MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_AUTH_TOKEN=replace-with-a-random-secret-of-at-least-32-bytes \
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com \
MCP_HTTP_ALLOWED_ORIGINS=console.example.com \
pnpm mcp:http

組み込みの Bearer トークンは、範囲が限定されたセルフホスト用の制御機能であり、OAuth 認可サーバーではありません。信頼できる TLS リバースプロキシで TLS を終端し、信頼できないネットワークにエンドポイントを公開する前に、専用の ID レイヤーを使用してください。公開済みの v0.5.0 コンテナーは引き続き stdio 専用です。上記の HTTP コマンドは、後続のリリースで公開されるまではソースビルド版の機能です。

Docker で Codex に追加する

クローンも API キーも必要ありません。

codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.8.0

専用イメージはデフォルトで MCP サーバーを起動するため、コマンドの上書きは不要です。また、Node を直接実行するため、パッケージマネージャーの出力が JSON-RPC ストリームに混入しません。OCI ID と stdio トランスポートは、公式 MCP レジストリ向けにリポジトリルートの server.json で宣言されています。

同等の config.toml エントリは次のとおりです。

[mcp_servers.unified_ai_system]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "ghcr.io/happy520ai/unified-ai-system/mcp-server:0.8.0",
]
startup_timeout_sec = 45
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

標準の JSON mcpServers 形式に対応するクライアントでは、汎用 MCP クライアント設定ガイドを参照してください。

Codex で試す

サーバーを追加した後、Codex を再起動してから /mcp verbose を実行し、接続されたツールを確認します。最初のタスクとして、次が役立ちます。

gateway_prompt_enhance を使用して、「チーム用の小さな API を作る」をコーディングプロンプトに変換します。保持された元のリクエスト、検出された言語、拡張されたプロンプト、プロバイダーが呼び出されなかったことを示す証拠を表示してください。

次に、フェイクチャットの安全境界を確認します。

Unified AI System MCP ツールを使用してゲートウェイのヘルスとレディネスを確認し、ゲートウェイがフェイク専用モードであることを証明できた場合に限り、ゲートウェイチャット経由で MCP_READY を送信してください。プロバイダー、モデル、実行モード、応答を報告してください。

Codex MCP の 60 秒クイックスタートには、安全なタスクがさらに 2 つ、期待される証拠、診断方法、削除コマンドが記載されています。

既存の安全なゲートウェイに接続する

AI_GATEWAY_MCP_URL と専用のゲートウェイアクセストークンを設定し、すでに実行中のインスタンスを使用します。

AI_GATEWAY_MCP_URL=http://127.0.0.1:3100 \
AI_GATEWAY_MCP_AUTH_TOKEN=<at-least-32-character-gateway-token> \
node packages/mcp-server/src/index.js

管理対象ゲートウェイでは、分離された子プロセスの存続期間によって有効期限が制限される、最小権限のプライベートトークンを使用します。このトークンが MCP の結果に出力されることはありません。外部ゲートウェイの起動では、トークンの未設定や強度不足、URL 認証情報、ループバック以外への平文 HTTP、無効な認証、または実際のプロバイダーを呼び出す可能性があるゲートウェイは拒否されます。プロバイダーの認証情報と実際のプロバイダーを使用する実行は、このプレビューの対象外です。

Agent Governance では、より広いオペレーターワークフローが明示的に必要でない限り、専用の Gateway ID には dashboard:read と workflow:run のみを付与してください。agent_governance_status には Gateway のプラットフォームテナント ID も必要です。通常のテナントでも、テナントのスコープ内でリスト、生成、説明を利用できます。これらのツールを使うためだけに、MCP モデルへ workflow:approve や user:admin を付与しないでください。

検証

テストでは、公式の MCP v2 クライアントを通じて両方のトランスポートを起動します。stdio と Streamable HTTP では、ステートレス化された最新の 2026-07-28 時代を対象とし、レガシーの 2025-11-25 と 2025-06-18 の初期化互換性を維持します。また、ソースビルドで利用可能なすべてのツールを列挙し、ローカルでのプロンプト強化と偽プロバイダーの安全性を検証し、HTTP/CORS のアクセス制御をテストし、クライアントを終了して、各管理対象ゲートウェイが停止したことを確認します。コンテナ対応の生スモークテストでも、SDK のバージョンから最新機能のサポートを推測するのではなく、server/discover とリクエストごとの _meta エンベロープを使用します。

pnpm verify:mcp