CAPI Gateway

CAPI Gateway

軽量 API ゲートウェイ

CAPI は Undertow の非同期プロキシアーキテクチャを基盤とする、軽量な API ゲートウェイ兼ロードバランサーです。サービスは HashiCorp Consul に自ら登録され、CAPI はサービスを自動的に検出してプロキシハンドラーを作成し、セキュリティ、スロットリング、オブザーバビリティのポリシーを適用します。データベースは不要です。

機能

• REST、WebSocket、SSE に対応したゲートウェイ。完全な非同期プロキシにより、バックエンド呼び出し中にスレッドをブロックしません
• HashiCorp Consul によるサービスディスカバリー（ルートの自動作成と削除）
• OAuth2 / OIDC トークン検証（複数プロバイダーに対応。Cookie ベースの認証もサポート）
• API キー認証とキーごとのスロットリング（Consul KV 経由）
• OPA（Open Policy Agent）によるきめ細かな認可（非同期ポリシー評価）
• 分散スロットリング（Hazelcast、Kubernetes ディスカバリー対応）
• ロードバランシング（ラウンドロビン）とフェイルオーバー
• 分散トレーシング（OpenTelemetry / OTLP）
• Prometheus メトリクス
• アップストリームサービスの OpenAPI 仕様の集約
• TLS 終端とトラストストアの動的管理（Consul KV 経由のホットリロード）
• CORS 管理
• ヘルス、メトリクス、ルートを確認できる管理 API
• 複数インスタンス対応（CAPI インスタンスごとのルート指定）
• リバースプロキシヘッダー（X-Forwarded-*）
• [Experimental] MCP ゲートウェイ — サービスを MCP ツールとして公開し、LLM エージェントから利用可能にします（Streamable HTTP 上の JSON-RPC 2.0）
• [Experimental] gRPC ゲートウェイ — ヘッダーベースのルーティングに対応した、gRPC サービス向けの透過的な HTTP/2 リバースプロキシ

REST から MCP へのブリッジ

CAPI の MCP ゲートウェイは、バックエンドにコード変更を加えることなく、既存のあらゆる REST API を MCP ツールに変換します。

MCP メタデータを付けて Consul にサービスを登録すると、LLM エージェント（Claude Desktop、Cursor、カスタムエージェント）はすぐにサービスを検出して呼び出せます。REST サービス側で MCP、JSON-RPC、ツールスキーマについて意識する必要はありません。変換は CAPI が処理します。

LLM Agent                          CAPI                          Your REST API
                                                                 (unchanged)
  tools/list  ──────────────►  reads Consul metadata
              ◄──────────────  returns tool catalog

  tools/call  ──────────────►  extracts arguments
              {"name":"..."}   POST /endpoint  ──────────────►  handles request
                               wraps response  ◄──────────────  returns JSON
              ◄──────────────  MCP-formatted result

CAPI は、すでに JSON-RPC 2.0 を使用している実際の MCP サーバーバックエンドにも対応しています。mcp-type: server を指定して登録すると、CAPI は tools/list を通じてツールを自動的に検出し、tools/call リクエストを透過的にプロキシします。REST バックエンドと MCP サーバーバックエンドは、どちらも統一された 1 つの MCP エンドポイントに集約されます。

すべてのバックエンドが MCP サーバーであることを求める専用 MCP ゲートウェイとは異なり、CAPI は既存の REST インフラストラクチャと LLM ネイティブなプロトコルの間を橋渡しします。実際に動作する例については、MCP Gateway のドキュメントとデモをご覧ください。両方のバックエンドタイプを使用しています。

クイックスタート

CAPI の実行には、有効な設定ファイルを指す環境変数 CAPI_CONFIG_FILE が必要です。

JAR から実行

CAPI_CONFIG_FILE=config/config.yaml java -jar capi-core.jar

Docker で実行

docker run -p 8380:8380 -p 8381:8381 \
  -v $(pwd)/config/config.yaml:/capi/config/config.yaml \
  -e CAPI_CONFIG_FILE=/capi/config/config.yaml \
  surisoft/capi-core

Helm で実行（Kubernetes）

Helm チャートは helm/capi-core/ にあります。

helm install capi-core helm/capi-core

# With custom values
helm install capi-core helm/capi-core -f my-values.yaml

# Enable SSL and truststore
helm install capi-core helm/capi-core \
  --set capi.ssl.enabled=true \
  --set capi.ssl.keystoreBase64=<base64-encoded-keystore> \
  --set capi.ssl.password=changeit

利用可能な設定オプションについては、helm/capi-core/values.yaml をご覧ください。

ポート

ポート	説明	設定キー
8380	REST API ゲートウェイ	capi.rest.port
8381	管理／メトリクス	capi.adminPort
8382	WebSocket ゲートウェイ	capi.websocket.port
8383	MCP ゲートウェイ（実験的）	capi.mcp.port
8384	gRPC ゲートウェイ（実験的）	capi.grpc.port

実行モード

runningMode フィールドでは、CAPI がプロキシするサービスの種類を制御します。

モード	説明
full	REST、WebSocket、SSE サービスをプロキシします（デフォルト）
websocket	WebSocket サービスのみをプロキシします
sse	SSE サービスのみをプロキシします

ドキュメント

ドキュメント	説明
サービス登録	Consul でサービスを登録し、メタデータを使ってルーティング、セキュリティ、スロットリングを設定する方法
セキュリティ	OAuth2/OIDC と OPA の認可設定
管理 API	管理エンドポイントのリファレンス（ヘルス、メトリクス、ルート、OpenAPI）
設定リファレンス	すべてのフィールドを網羅した YAML 設定リファレンス
MCP ゲートウェイ（実験的）	JSON-RPC 2.0 を介した LLM ツール統合のための MCP ゲートウェイ
gRPC ゲートウェイ（実験的）	ヘッダーベースのルーティングに対応した透過的な gRPC リバースプロキシ