MCP Gateway

🚀 MCP Gateway

MCP Gatewayは、複数のModel Context Protocol (MCP)サーバーを1つのゲートウェイに接続するサーバー集約ツールです。接続されたサーバーのすべてのツールを統一された検索、説明、呼び出しインターフェースを通じて公開し、たった5つのツールのみを公開します。

🚀 クイックスタート

MCP Gatewayは、MCPクライアント（Claude Code、Opencodeなど）を複数のMCPサーバーに接続する際に発生する問題を解決するために開発されまし。以下に、主な機能と使用方法を説明します。

✨ 主な機能

コンテキスト制限問題の解決

クライアント（Claude Code、Opencodeなど）を複数のMCPサーバーに接続すると、各サーバーがすべてのツールをリストアップします。10以上のMCPがそれぞれ10 - 50のツールを公開する場合、システムプロンプト内のツール説明が500以上になることがあります。これにより、以下の2つの問題が発生します。

1. コンテキストオーバーフロー：多くのLLMは会話が始まる前にコンテキスト制限に達します。
2. 認知的負荷：LLMは数百のオプションから適切なツールを選択するのに苦労します。

ゲートウェイによる解決策

MCP Gatewayは、すべてのツールスキーマを一括表示するのではなく、ツール検索を提供することでこれらの問題を解決します。

┌─────────────┐    gateway.search    ┌─────────────────┐    kubernetes::pods_list    ┌──────────────────┐
│  AI Client  │ ───────────────────► │   MCP Gateway   │ ─────────────────────────►  │  Kubernetes MCP  │
│             │                      │                 │                             │                  │
│             │ ◄────────────────────│                 │ ◄─────────────────────────  │                  │
└─────────────┘   pods_list schema   └─────────────────┘         pods output         └──────────────────┘

動作原理

MCP Gatewayは、MCPクライアント（上流サーバーに接続）とMCPサーバー（下流クライアントにツールを公開）の両方として動作します。

┌──────────────┐      MCP       ┌─────────────────┐      MCP       ┌──────────────────┐
│  AI Client   │ ◄────────────  │   MCP Gateway   │ ◄────────────  │  Upstream Server │
│ (Claude, etc)│                │  (this gateway) │                │  (playwright,    │
└──────────────┘                └─────────────────┘                │   kubernetes...) │
                                                                   └──────────────────┘

1. ゲートウェイが起動し、設定を読み込みます。
2. 設定された各上流サーバーに対して、ゲートウェイはstdio（ローカル）またはHTTP/WebSocket（リモート）を介して接続します。
3. ゲートウェイは各サーバーからツールカタログを取得します。
4. すべてのツールは、検索機能を持つ統一カタログにインデックスされます。
5. AIクライアントはゲートウェイに接続し、gateway.searchを使用して関連するツールを検索します。
6. クライアントが実際に必要とするツールのみが呼び出されます。

これにより、初期トークンの使用量が約40％削減されます。

📦 インストール

Claude Code

Claude MCPの設定に以下を追加します。

{
  "mcpServers": {
    "gateway": {
      "command": "bunx",
      "args": ["@eznix/mcp-gateway@latest"]
    }
  }
}

OpenCode

OpenCode MCPの設定に以下を追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-gateway": {
      "type": "local",
      "command": ["bunx", "@eznix/mcp-gateway@latest"]
    },
  }
}

グローバルのAGENTS.md (~/.config/opencode/AGENTS.md)にこのテンプレートを追加することができます。これで、利用可能なMCPを簡単に列挙できます。

📚 詳細ドキュメント

設定

MCP GatewayはJSONファイルから設定を読み込みます。デフォルトでは、以下の順で設定ファイルを探します。

1. コマンドライン引数として指定されたパス
2. MCP_GATEWAY_CONFIG環境変数
3. ~/.config/mcp-gateway/config.json

設定フォーマット

{
  "local-server": {
    "type": "local",
    "command": ["bun", "run", "/path/to/server.ts"],
  },
  "remote-server": {
    "type": "remote",
    "url": "https://mcp.example.com",
    "enabled": true
  },
  "websocket-server": {
    "type": "remote",
    "url": "wss://mcp.example.com/ws",
    "enabled": true
  }
}

各エントリは以下を指定します。

• type: "local" または "remote"
• command (ローカルのみ): 上流サーバーを起動するためのコマンドと引数の配列
• url (リモートのみ): リモートMCPサーバーの完全なURL
• transport (オプション、リモートのみ): トランスポート検出を上書きします ("streamable_http" または "websocket")。通常はURLプロトコルから自動検出されます。
• environment (ローカルのみ): 起動するプロセスに渡す環境変数で、{env:VAR_NAME} 置換をサポートします。
• enabled: このサーバーへの接続をスキップするには false に設定します。

置換を伴う環境変数

ローカルのMCPサーバーは、{env:VAR_NAME} 構文を使用した環境変数の置換をサポートしています。

{
  "jupyter-lab": {
    "type": "local",
    "command": ["uvx", "jupyter-mcp-server@latest"],
    "environment": {
      "JUPYTER_URL": "http://localhost:{env:JUPYTER_PORT}/",
      "JUPYTER_TOKEN": "{env:JUPYTER_TOKEN}",
      "DEBUG": "true"
    }
  }
}

{env:VAR_NAME} のプレースホルダーは、現在のプロセス環境から解決されます。環境変数が設定されていない場合、空の文字列に置き換えられます。

Docker

HTTPトランスポートでDocker内でMCP Gatewayを実行します。

# イメージをビルドする
docker build -t mcp-gateway .

# 設定をマウントして実行する
docker run -p 3000:3000 \
  -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro \
  mcp-gateway

エンドポイント:

例:

curl http://localhost:3000/
# {"name":"MCP Gateway",...,"endpoints":{"mcp":"/mcp","health":"/health"}}

curl http://localhost:3000/health
# {"status":"ok"}

リモートサーバーの設定

リモートサーバーは、URLプロトコルに基づいて自動検出されます。

• http:// または https:// → Streamable HTTP（推奨）
• ws:// または wss:// → WebSocket

{
  "gh-grep": {
    "type": "remote",
    "url": "https://mcp.grep.app"
  },
  "custom-websocket": {
    "type": "remote",
    "url": "wss://my-server.com/mcp"
  }
}

💻 使用例

gateway.search

接続されたすべてのサーバーでツールを検索します。

{
  query: "kubernetes pods",
  limit: 10,  // オプション、最大50
  filters: {
    server: "kubernetes",  // オプション、サーバー名でフィルタリング
  }
}

関連性スコア付きで一致するツールを返します。名前が一致するツールは優先されます。

gateway.describe

特定のツールに関する詳細情報を取得します。

{
  id: "kubernetes::pods_list"  // 形式: serverKey::toolName
}

入力スキーマを含む完全なツールスキーマを返します。

gateway.invoke

ツールを同期的に実行し、即座に結果を取得します。

{
  id: "kubernetes::pods_list",
  args: { namespace: "default" },
  timeoutMs: 30000  // オプション、デフォルト30秒
}

gateway.invoke_async

非同期ツールの実行を開始します。ポーリング用のジョブIDを返します。

{
  id: "some-server::long-running-tool",
  args: { ... },
  priority: 10,  // オプション、値が高いほど優先度が高い
  timeoutMs: 60000
}

gateway.invoke_status

非同期ジョブのステータスを確認します。

{
  jobId: "job_123456789_abc123"
}

ツールIDの形式

すべてのゲートウェイツールは、serverKey::toolName の形式を使用してツールを識別します。

kubernetes::pods_list
playwright::browser_navigate
github::create_issue

serverKey は設定ファイル内のキー名です。

🔧 技術詳細

コンポーネント

• MCPGatewayクラス: メインオーケストレーター
• 上流接続マネージャー: MCPサーバーへの接続を管理します（ローカルの場合はstdio、リモートの場合はHTTP/WebSocket）
• ツールカタログ: メタデータ付きのすべての利用可能なツールのインメモリインデックス
• ジョブキュー: 優先順位付けと同時実行数制限（デフォルトで最大3同時実行）で非同期ツールの呼び出しを処理します
• 検索エンジン: BM25スコアリングとファジーマッチングを備えたMiniSearch

検索アルゴリズム

検索にはMiniSearchとBM25ランキングが使用されています。

• BM25スコアリング: 関連性アルゴリズム
• フィールドブースト: 名前の一致（3倍）、タイトルの一致（2倍）、説明/サーバーの一致（1倍）
• ファジーマッチング: 0.2の閾値でタイポを処理します（例: "kubenetes" → "kubernetes" を検索）
• 接頭辞検索: 部分的な単語の一致（例: "pod" は "pods_list" に一致）

コントリビュート

git clone https://github.com/eznix86/mcp-gateway.git
cd mcp-gateway
bun install

# ローカルで実行する（stdioトランスポート）
bun run index.ts

# Dockerで実行する（ポート3000でHTTPトランスポート）
bun run docker:build && bun run docker:run

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEを参照してください。