MCP Proxy Server

Name: MCP Proxy Server
Author: ptbsare

ローカル

github.com/ptbsare開発ツール19665 週間前に更新

リポジトリ

MCP Proxy Server について

MCP Proxy Serverは複数のバックエンドMCPサーバーを集約し、ツールとリソースを統一エンドポイントで公開します。Stdio、SSE、Streamable HTTPのサーバーをまとめて管理する運用者向けで、任意のWeb管理画面とエンドポイント認証を備えます。

主な機能

01Stdio、SSE、HTTPバックエンドへの接続
02ツールとリソースの集約
03バックエンドへのリクエスト振り分け
04任意のWeb管理画面
05ツールの表示設定と名称変更
06HTTPエンドポイント認証

活用シーン

01複数のMCPサーバーを単一エンドポイントで公開
02特定のバックエンドツールの無効化や改名
03ブラウザーでのサーバー設定管理
04APIキーやトークンによるHTTPエンドポイント保護

MCP 対応

Stdio、SSE、Streamable HTTPでバックエンドMCPサーバーに接続し、集約したツールとリソースをSSE、Streamable HTTP、またはStdio経由でMCPクライアントに公開します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "proxy-server-ptbsare": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pull"
      ]
    }
  }
}

起動コマンドdocker run -i --rm pull

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

ocipullstdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

MCP Proxy Server

简体中文

✨ 主な機能

🌐 Web UI による管理： 直感的な Web インターフェースを通じて、接続されているすべての MCP サーバーを簡単に管理できます（オプション。有効化が必要です）。
🔧 詳細なツール制御： 個々のツールを有効または無効にでき、Web UI から名前や説明を上書きできます。
🛡️ 柔軟なエンドポイント認証： 柔軟な認証オプション（Authorization: Bearer <token> または X-API-Key: <key>）を使用して、HTTP ベースのエンドポイント（/sse、/mcp）を保護できます。
🔄 堅牢なセッション処理と同時接続：
- クライアントの再接続時の SSE セッション処理（サーバー送信の endpoint イベントを利用）を改善し、同時接続にも対応しています。
- ストリーミング可能な HTTP エンドポイント（/mcp）も、複数クライアントによる同時操作に対応しています。
🚀 多様な MCP 操作（サーバーとプロキシ）：
- プロキシとして動作： さまざまなタイプ（Stdio、SSE、ストリーミング可能な HTTP）の複数のバックエンド MCP サーバーに接続し、それらを集約します。
- サーバーとして動作： 集約した機能を、独自のストリーミング可能な HTTP（/mcp）および SSE（/sse）エンドポイントを通じて公開します。Stdio 専用モードで実行することもできます。
✨ インストール出力をリアルタイム表示：Stdio サーバーのインストール状況（stdout/stderr）を Web UI で直接確認できます。
✨ Web ターミナル：管理 UI 内のコマンドラインターミナルから、サーバーを直接操作できます（オプション。セキュリティリスクがあるため、慎重に使用してください）。

このサーバーは、Model Context Protocol（MCP）リソースサーバーの中央ハブとして動作します。以下の機能があります。

複数のバックエンド MCP サーバー（Stdio、SSE、ストリーミング可能な HTTP タイプ）に接続して管理します。
それらの機能（ツール、リソース）を単一の統合された SSE インターフェース、ストリーミング可能な HTTP インターフェースを通じて公開するか、または単一の Stdio ベースの MCP サーバーとして動作します。
リクエストを適切なバックエンドサーバーにルーティングします。
必要に応じてレスポンスを集約します（ただし、主にプロキシとして動作します）。
オプションの API キー認証を使用して、複数の SSE クライアント接続を同時にサポートします。

機能

プロキシによるリソースとツールの管理

config/mcp_server.json で定義された複数の MCP リソースサーバーを検出して接続します。
接続されているすべてのアクティブなサーバーから、ツールとリソースを集約します。
ツール呼び出しとリソースアクセスのリクエストを、正しいバックエンドサーバーにルーティングします。
一貫性のある URI スキームを維持します。

✨ オプションの Web 管理 UI（`ENABLE_ADMIN_UI=true`）

プロキシサーバーの設定と接続されているツールを管理するための、ブラウザベースのインターフェースを提供します。主な機能は次のとおりです。

サーバー設定： サーバーエントリー（mcp_server.json）の表示、追加、編集、削除ができます。関連オプション（タイプ、コマンド、引数、環境変数、URL、API キー、ベアラートークン、インストール設定）を使用して、Stdio、SSE、HTTP の各サーバータイプをサポートします。
ツール設定： アクティブなバックエンドサーバーから検出されたすべてのツールを表示します。特定のツールを有効または無効にできます。各ツールの表示名と説明を上書きできます（tool_config.json）。
ライブリロード： プロキシサーバープロセス全体を再起動せずに、設定を再読み込みしてサーバーとツールの設定変更を適用します。
Stdio サーバーのインストール： Stdio サーバーでは、設定でインストールコマンドを定義できます。管理 UI では、次の操作ができます。
- これらのインストールコマンドを実行します。
- UI に直接ストリーミングされる stdout と stderr のライブ出力で、インストールの進行状況をリアルタイムで確認できます。
Web ターミナル： プロキシサーバーが実行されている環境へのシェルアクセスを提供する、統合型の Web ベースターミナルを利用できます。
- セキュリティ警告： この機能では広範なアクセスが可能になるため、特に管理インターフェースを公開する場合は、細心の注意を払って使用してください。

設定

設定は主に、環境変数と ./config ディレクトリ内の JSON ファイルで行います。

1. サーバー接続（`config/mcp_server.json`）

このファイルでは、プロキシが接続するバックエンド MCP サーバーを定義します。

config/mcp_server.json の例：

{
  "mcpServers": {
    "unique-server-key1": {
      "type": "stdio",
      "name": "My Stdio Server",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "type": "sse",
      "name": "My SSE Server",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "http-mcp-server": {
      "type": "http",
      "name": "My Streamable HTTP Server",
      "active": true,
      "url": "http://localhost:8081/mcp",
      "bearerToken": "some_secure_token_for_http_server"
    },
    "stdio-default-install": {
        "type": "stdio",
        "name": "Stdio Server with Default Install Path",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo 'Installing to default location...'"]
    }
  }
}

フィールド：

mcpServers：（必須）各キーがバックエンドサーバーの一意の識別子となるオブジェクトです。
name：（任意）サーバーのユーザー向け表示名です（管理 UI で使用されます）。
active：（任意、デフォルト：true）false に設定すると、プロキシはこのサーバーに接続しません。
type：（必須）トランスポートの種類を指定します。"stdio"、"sse"、"http" のいずれかである必要があります。
command：（type が "stdio" の場合は必須）サーバープロセスを実行するコマンドです。
args：（type が "stdio" の場合は任意）コマンドに渡す文字列引数の配列です。
env：（type が "stdio" の場合は任意）サーバープロセスに設定する環境変数（KEY: "value"）のオブジェクトです。プロキシサーバーの環境変数と統合されます。
url：（type が "sse" または "http" の場合は必須）バックエンドサーバーのエンドポイントの完全な URL です（例："sse" の場合は SSE エンドポイント、"http" の場合は MCP エンドポイント）。
apiKey：（type が "sse" または "http" の場合は任意）プロキシがこの特定のバックエンドサーバーに接続する際に、X-Api-Key ヘッダーで送信する API キーです。
bearerToken：（type が "sse" または "http" の場合は任意）この特定のバックエンドサーバーに接続する際に、Authorization: Bearer <token> ヘッダーで送信するトークンです。（apiKey と bearerToken の両方が指定されている場合、通常、そのバックエンドへの接続では bearerToken が優先されます）。
installDirectory：（type が "stdio" の場合は任意）サーバー自体をインストールする絶対パスです（例：/opt/my-server-files）。管理 UI のインストール機能で使用されます。
- mcp_server.json で指定されている場合、このパスがそのまま使用されます。
- 省略した場合、使用されるディレクトリは TOOLS_FOLDER 環境変数によって異なります（環境変数のセクションを参照）。
  - TOOLS_FOLDER が設定され、空でない場合、サーバーはこのフォルダー内のサーバーキーにちなんだ名前のサブディレクトリにインストールされます（例：${TOOLS_FOLDER}/<server_key>）。
  - TOOLS_FOLDER も空、または未設定の場合、プロキシサーバーの作業ディレクトリ内の tools サブディレクトリがデフォルトで使用されます（例：./tools/<server_key>）。
- インストール先パスの親ディレクトリ（例：TOOLS_FOLDER または ./tools）に、プロキシサーバーの実行ユーザーが書き込めることを確認してください。
installCommands：（stdio タイプの場合は任意）対象サーバーディレクトリ（installDirectory から導出、またはデフォルト）が存在しない場合に、管理 UI のインストール機能が順番に実行するシェルコマンドの配列です。コマンドは、対象サーバーのインストールディレクトリの親ディレクトリから実行されます（例：installDirectory が /opt/tools/my-server に解決される場合、コマンドは /opt/tools/ で実行されます）。セキュリティ上のリスクがあるため、細心の注意を払って使用してください。

2. ツール設定（`config/tool_config.json`）

このファイルでは、バックエンドサーバーから検出されたツールのプロパティを上書きできます。主に管理 UI から管理しますが、手動で編集することもできます。

config/tool_config.json の例：

{
  "tools": {
    "unique-server-key1__tool-name-from-server": {
      "enabled": true,
      "displayName": "My Custom Tool Name",
      "description": "A more user-friendly description."
    },
    "another-sse-server__another-tool": {
      "enabled": false
    }
  }
}

キーは <server_key><separator><original_tool_name> の形式です。<separator> は SERVER_TOOLNAME_SEPERATOR 環境変数の値です（デフォルトは __）。
enabled：（任意、デフォルト：true）false に設定すると、プロキシに接続するクライアントからこのツールが非表示になります。
displayName：（任意）クライアント UI に表示されるツール名を上書きします。
description：（任意）ツールの説明を上書きします。

3. 環境変数

PORT：プロキシサーバーの HTTP ベースのエンドポイント（/sse、/mcp、有効な場合は Admin UI）のポートです。デフォルト：3663。**注：**これは、HTTP サーバーを起動するモード（例：npm run dev:sse または Docker コンテナ）で実行する場合にのみ使用されます。npm run dev スクリプトは Stdio モードで実行されます。
```
export PORT=8080
```
ALLOWED_KEYS：（任意）プロキシの HTTP ベースのエンドポイント（/sse、/mcp）を保護するための API キーを、カンマ区切りで指定します。ALLOWED_KEYS と ALLOWED_TOKENS のどちらも設定されていない場合、これらのエンドポイントでは認証が無効になります。クライアントは X-Api-Key ヘッダーまたは ?key= クエリパラメーターでキーを指定する必要があります。
```
export ALLOWED_KEYS="client_key1,client_key2"
```
ALLOWED_TOKENS：（任意）プロキシの HTTP ベースのエンドポイント（/sse、/mcp）を保護するための Bearer Token を、カンマ区切りで指定します。ALLOWED_KEYS と ALLOWED_TOKENS のどちらも設定されていない場合、認証は無効になります。クライアントは Authorization: Bearer <token> ヘッダーでトークンを指定する必要があります。ALLOWED_KEYS と ALLOWED_TOKENS の両方が設定されている場合は、Bearer Token 認証が先に試行されます。
```
export MCP_PROXY_SSE_ALLOWED_TOKENS="your_bearer_token_1,your_bearer_token_2"
```
ENABLE_ADMIN_UI：（任意）Web Admin UI を有効にするには true に設定します（SSE モードでのみ適用されます）。デフォルト：false。
```
export ENABLE_ADMIN_UI=true
```
ADMIN_USERNAME：（Admin UI が有効な場合は必須）Admin UI ログイン用のユーザー名です。デフォルト：admin。
ADMIN_PASSWORD：（Admin UI が有効な場合は必須）Admin UI ログイン用のパスワードです。デフォルト：password（変更してください！）。
```
export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!
```
SESSION_SECRET：（任意。Admin UI が有効な場合は設定を推奨）セッション Cookie の署名に使用するシークレットです。設定されていない場合、安全性の低いデフォルトのシークレットが使用され、警告が出力されます。環境変数で指定されていない場合は、初回実行時に安全なシークレットが自動生成され、config/.session_secret に保存されます。
```
# 推奨：強力なシークレットを生成します（例：openssl rand -hex 32）
export SESSION_SECRET='your_very_strong_random_secret_here'
```
TOOLS_FOLDER：（任意）Admin UI から開始した Stdio サーバーのインストール先のベースディレクトリを指定します。特定のサーバーの mcp_server.json で installDirectory が明示的に設定されていない場合に使用されます。
- 設定されている場合（例：/custom/tools_path）、特定の installDirectory が設定されていないサーバーのインストール先は、このフォルダー内のサーバーキー名のサブディレクトリになります（例：${TOOLS_FOLDER}/<server_key>）。
- TOOLS_FOLDER が設定されていないか空の場合、インストール先はプロキシサーバーの作業ディレクトリ内の tools サブディレクトリになります（例：./tools/<server_key>）。
- Dockerfile では、デフォルトで /tools に設定されています。
```
export TOOLS_FOLDER=/srv/mcp_tools
```
SERVER_TOOLNAME_SEPERATOR：（任意）ツールの一意のキー（例：server-key__tool-name）を生成する際に、サーバー名とツール名を結合する区切り文字を定義します。このキーは内部および tool_config.json ファイルで使用されます。
- デフォルト：__。
- 2 文字以上で、英字（a-z、A-Z）、数字（0-9）、ハイフン（-）、アンダースコア（_）のみを使用できます。
- 指定した値が無効な場合は、デフォルト（__）が使用され、警告がログに記録されます。
```
export SERVER_TOOLNAME_SEPERATOR="___" # 例：アンダースコアを3つ使用
```
LOGGING：（任意）サーバーが出力するログの最小レベルを制御します。
- 指定できる値（大文字と小文字を区別しません）：error、warn、info、debug。
- 指定したレベルおよびそれより上位のすべてのレベルのログが表示されます。
- デフォルト：info。
```
export LOGGING="debug"
```
RETRY_SSE_TOOL_CALL：（任意）SSE ツール呼び出しの再試行を有効にするかどうかを制御します。有効にするには "true"、無効にするには "false" を設定します。デフォルト：true。詳細は「信頼性強化機能」のセクションを参照してください。
```
export RETRY_SSE_TOOL_CALL="true"
```
SSE_TOOL_CALL_MAX_RETRIES：（任意）SSE ツール呼び出しの最大再試行回数（最初の失敗後）。デフォルト：2。詳細は「信頼性強化機能」のセクションを参照してください。
```
export SSE_TOOL_CALL_MAX_RETRIES="2"
```
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS：（任意）指数バックオフに使用する、SSE ツール呼び出しの再試行における基本待機時間（ミリ秒）。デフォルト：300。詳細は「信頼性強化機能」のセクションを参照してください。
```
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="300"
```
RETRY_HTTP_TOOL_CALL：（任意）HTTP ツール呼び出しの接続エラー時に再試行するかどうかを制御します。有効にするには "true"、無効にするには "false" を設定します。デフォルト：true。詳細は「信頼性強化機能」のセクションを参照してください。
```
export RETRY_HTTP_TOOL_CALL="true"
```
HTTP_TOOL_CALL_MAX_RETRIES：（任意）HTTP ツール呼び出しの最大再試行回数（最初の失敗後）。デフォルト：2。詳細は「信頼性強化機能」のセクションを参照してください。
```
export HTTP_TOOL_CALL_MAX_RETRIES="3"
```
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS：（任意）指数バックオフに使用する、HTTP ツール呼び出しの再試行における基本待機時間（ミリ秒）。デフォルト：300。詳細は「信頼性強化機能」のセクションを参照してください。
```
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"
```
RETRY_STDIO_TOOL_CALL：（任意）Stdio ツール呼び出しの接続エラー時に再試行するかどうかを制御します（プロセスの再起動を試みます）。有効にするには "true"、無効にするには "false" を設定します。デフォルト：true。詳細は「信頼性強化機能」のセクションを参照してください。
```
export RETRY_STDIO_TOOL_CALL="true"
```
STDIO_TOOL_CALL_MAX_RETRIES：（任意）Stdio ツール呼び出しの最大再試行回数（最初の失敗後）。デフォルト：2。詳細は「信頼性強化機能」のセクションを参照してください。
```
export STDIO_TOOL_CALL_MAX_RETRIES="5"
```
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS：（任意）指数バックオフに使用する、Stdio ツール呼び出しの再試行における基本待機時間（ミリ秒）。デフォルト：300。詳細は「信頼性強化機能」のセクションを参照してください。
```
export STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS="1000"
```

信頼性強化機能

MCP Proxy Server には、バックエンド MCP サービスとのやり取りの回復力と信頼性を高め、より円滑な運用と安定したツール実行を実現する機能が含まれています。

1. エラーの伝播

プロキシサーバーは、バックエンド MCP サービスで発生したエラーが、要求元のクライアントに一貫して伝播されるようにします。これらのエラーは標準的な JSON-RPC エラーレスポンスとして整形されるため、クライアントは一貫した方法で処理できます。

2. SSE ツール呼び出しの再試行

SSE ベースのバックエンドサーバーに対して tools/call 操作を行った際、基盤となる接続が切断されたりエラーが発生したりした場合（タイムアウトを含む）、プロキシサーバーは再試行メカニズムを実装します。

再試行メカニズム： 最初の SSE ツール呼び出しが接続エラーまたはタイムアウトによって失敗すると、プロキシは SSE バックエンドへの接続の再確立を試みます。再接続に成功した場合、HTTP および Stdio の再試行と同様の指数バックオフ方式を使用して、元の tools/call リクエストを再試行します。つまり、再試行のたびに待機時間が指数関数的に増加し、さらに少量のジッター（ランダムな変動）が加わります。

設定： これらの設定は主に環境変数によって制御されます。特定のキーについて、proxy オブジェクト内の config/mcp_server.json の値は、環境変数が設定されている場合、その値で上書きされます。

RETRY_SSE_TOOL_CALL（環境変数）：
- "true" に設定すると、SSE ツール呼び出しの再試行が有効になります。
- "false" に設定すると、この機能が無効になります。
- デフォルトの動作： true（環境変数が設定されていない場合、空の場合、または無効な値の場合）。
SSE_TOOL_CALL_MAX_RETRIES（環境変数）：
- 最初の失敗後に再試行する最大回数を指定します。たとえば "2" に設定すると、最初の試行が 1 回、再試行が最大 2 回となり、合計で最大 3 回試行されます。
- デフォルトの動作： 2（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS（環境変数）：
- 指数バックオフの計算に使用される、ミリ秒単位の基本待機時間です。n 回目の再試行（0 起点）の前の待機時間は、おおよそ SSE_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter です。
- デフォルトの動作： 300（ミリ秒）（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。

例（環境変数）：

export RETRY_SSE_TOOL_CALL="true"
export SSE_TOOL_CALL_MAX_RETRIES="3"
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

3. ツール呼び出しの HTTP リクエスト再試行

HTTP ベースのバックエンドサーバーに対する tools/call 操作では、プロキシは接続エラー（「failed to fetch」やネットワークタイムアウトなど）に対する再試行メカニズムを実装します。

再試行メカニズム： 最初の HTTP リクエストが接続エラーによって失敗すると、プロキシは指数バックオフ方式を使用してリクエストを再試行します。つまり、再試行のたびに待機時間が指数関数的に増加し、さらに少量のジッター（ランダムな変動）が加わるため、サンダリングハードの発生を防げます。

設定： これらの設定は主に環境変数によって制御されます。

RETRY_HTTP_TOOL_CALL（環境変数）：
- "true" に設定すると、HTTP ツール呼び出しの再試行が有効になります。
- "false" に設定すると、この機能が無効になります。
- デフォルトの動作： true（環境変数が設定されていない場合、空の場合、または無効な値の場合）。
HTTP_TOOL_CALL_MAX_RETRIES（環境変数）：
- 最初の失敗後に再試行する最大回数を指定します。たとえば "2" に設定すると、最初の試行が 1 回、再試行が最大 2 回となり、合計で最大 3 回試行されます。
- デフォルトの動作： 2（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS（環境変数）：
- 指数バックオフの計算に使用される、ミリ秒単位の基本待機時間です。n 回目の再試行（0 起点）の前の待機時間は、おおよそ HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter です。
- デフォルトの動作： 300（ミリ秒）（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。

4. ツール呼び出しの Stdio 接続リトライ

Stdio ベースのバックエンドサーバーを対象とする tools/call 操作では、プロキシは接続エラー（プロセスのクラッシュや応答なしなど）に対するリトライ機構を実装しています。

リトライ機構： Stdio 接続の初回試行またはツール呼び出しが失敗した場合、プロキシは Stdio プロセスを再起動してリクエストを再試行します。この機構では、HTTP のリトライと同様の指数バックオフ方式を採用しています。

設定： これらの設定は主に環境変数で制御します。

RETRY_STDIO_TOOL_CALL（環境変数）：
- "true" に設定すると、Stdio のツール呼び出しをリトライします。
- "false" に設定すると、この機能を無効にします。
- デフォルトの動作： true（環境変数が設定されていない、空、または無効な値の場合）。
STDIO_TOOL_CALL_MAX_RETRIES（環境変数）：
- 最初の失敗後に行うリトライの最大回数を指定します。たとえば、"2" に設定すると、最初の試行が 1 回、リトライが最大 2 回となり、合計で最大 3 回試行します。
- デフォルトの動作： 2（環境変数が設定されていない、空、または有効な整数でない場合）。
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS（環境変数）：
- 指数バックオフの計算に使用する基本遅延時間をミリ秒単位で指定します。n 回目（0 始まり）のリトライ前の遅延時間は、おおよそ STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter です。
- デフォルトの動作： 300（ミリ秒）（環境変数が設定されていない、空、または有効な整数でない場合）。

環境変数の解析に関する一般的な注意事項：

ブール値の環境変数（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）は、小文字に変換した値が正確に "true" の場合に true とみなされます。それ以外の値（空または未設定を含む）の場合はデフォルト値が適用され、デフォルト値が false の場合は false になります（ただし、これらの変数のデフォルト値は true です）。
数値の環境変数（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）は、10 進整数として解析されます。解析に失敗した場合（値が数値でない、または変数が空もしくは未設定の場合など）は、デフォルト値が使用されます。

開発

MCP Proxy Server には、バックエンド MCP サービスとのやり取りの回復力と信頼性を高め、処理を円滑にし、ツールをより安定して実行する機能が備わっています。

1. エラーの伝播

プロキシサーバーは、バックエンド MCP サービスで発生したエラーを、リクエスト元のクライアントに一貫して伝播します。これらのエラーは標準的な JSON-RPC エラーレスポンスとしてフォーマットされるため、クライアントはエラーを統一的に処理しやすくなります。

2. ツール呼び出し時の SSE 接続再試行

SSE ベースのバックエンドサーバーに対して tools/call 操作を行った際、基盤となる接続が切断されたりエラーが発生したりすると、プロキシサーバーは自動的に次の処理を試みます。

SSE バックエンドへの接続を再確立します。
再接続に成功した場合、元の tools/call リクエストを一度だけ再試行します。

この動作により、SSE 接続が一時的に中断される原因となるネットワークの一時的な問題を軽減できます。

設定： この機能は主に RETRY_SSE_TOOL_CALL_ON_DISCONNECT 環境変数で制御します。

RETRY_SSE_TOOL_CALL_ON_DISCONNECT（環境変数）：
- "true" に設定すると、自動再接続と再試行が有効になります。
- "false" に設定すると、この機能が無効になります。
- デフォルトの動作： true（環境変数が設定されていない場合、空の場合、または無効な値の場合）。
- 注：この設定が config/mcp_server.json の proxy の下にもある場合は、環境変数が優先されます。

例（環境変数）：

export RETRY_SSE_TOOL_CALL_ON_DISCONNECT="true"

（「プロキシ動作の設定」にある mcp_server.json の JSON の例は、その他のプロキシ設定を記述する場所を示していますが、この特定の設定は環境変数で管理することを推奨します。）

3. ツール呼び出し時の HTTP リクエスト再試行

HTTP ベースのバックエンドサーバーに対する tools/call 操作では、プロキシは接続エラー（「failed to fetch」やネットワークのタイムアウトなど）に対する再試行メカニズムを実装しています。

再試行メカニズム： 最初の HTTP リクエストが接続エラーで失敗すると、プロキシは指数バックオフ方式を使用してリクエストを再試行します。つまり、後続の再試行ごとに待機時間を指数関数的に増加させ、さらに少量のジッター（ランダム性）を加えることで、サーバーへのリクエスト集中を防ぎます。

設定： これらの設定は主に環境変数で制御します。config/mcp_server.json の proxy オブジェクトにあるこれらの特定のキーの値は、環境変数が設定されている場合、環境変数によって上書きされます。

RETRY_HTTP_TOOL_CALL（環境変数）：
- "true" に設定すると、HTTP ツール呼び出しの再試行が有効になります。
- "false" に設定すると、この機能が無効になります。
- デフォルトの動作： true（環境変数が設定されていない場合、空の場合、または無効な値の場合）。
HTTP_TOOL_CALL_MAX_RETRIES（環境変数）：
- 最初の失敗後に行う再試行の最大回数を指定します。たとえば "2" に設定すると、最初の試行が 1 回、再試行が最大 2 回となり、試行回数は合計で最大 3 回になります。
- デフォルトの動作： 2（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS（環境変数）：
- 指数バックオフの計算に使用する基本待機時間をミリ秒単位で指定します。n 回目の再試行（0 から数える）までの待機時間は、おおよそ HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter です。
- デフォルトの動作： 300（ミリ秒）（環境変数が設定されていない場合、空の場合、または有効な整数でない場合）。

環境変数の解析に関する一般的な注意事項：

ブール型環境変数（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）は、小文字に変換した値が正確に "true" の場合に true と見なされます。それ以外の値（空または未設定を含む）の場合は、デフォルト値が適用されます。デフォルト値が false の場合は false になります（ただし、これらの特定の変数のデフォルト値は true です）。
数値環境変数（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）は、10 進整数として解析されます。解析に失敗した場合（値が数値でない場合や、変数が空または未設定の場合など）は、デフォルト値が使用されます。

例（環境変数）：

export RETRY_HTTP_TOOL_CALL="true"
export HTTP_TOOL_CALL_MAX_RETRIES="3"
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

4. ツール呼び出しの Stdio 接続再試行

Stdio ベースのバックエンドサーバーを対象とする tools/call 操作では、プロキシが接続エラー（プロセスのクラッシュや応答停止など）に対する再試行メカニズムを実装しています。

再試行メカニズム： Stdio 接続またはツール呼び出しが最初に失敗した場合、プロキシは Stdio プロセスを再起動して、リクエストを再試行します。このメカニズムでは、HTTP の再試行と同様の指数バックオフ方式を採用しています。

設定： これらの設定は、主に環境変数で制御します。

RETRY_STDIO_TOOL_CALL（環境変数）：
- "true" に設定すると、Stdio のツール呼び出しの再試行が有効になります。
- "false" に設定すると、この機能が無効になります。
- デフォルトの動作： true（環境変数が未設定、空、または無効な値の場合）。
STDIO_TOOL_CALL_MAX_RETRIES（環境変数）：
- 最初の失敗後に行う再試行の最大回数を指定します。たとえば "2" に設定すると、最初の試行が 1 回、その後の再試行が最大 2 回となり、合計で最大 3 回試行されます。
- デフォルトの動作： 2（環境変数が未設定、空、または有効な整数でない場合）。
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS（環境変数）：
- 指数バックオフの計算に使う、ミリ秒単位の基本遅延時間です。n 回目（0 始まり）の再試行前の遅延は、おおよそ STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter です。
- デフォルトの動作： 300（ミリ秒）（環境変数が未設定、空、または有効な整数でない場合）。

環境変数の解析に関する一般的な注意事項：

ブール型の環境変数（RETRY_SSE_TOOL_CALL、RETRY_HTTP_TOOL_CALL、RETRY_STDIO_TOOL_CALL）は、小文字にした値が正確に "true" の場合に true として扱われます。それ以外の値（空または未設定を含む）の場合は、デフォルト値が適用されます。デフォルト値が false の場合は false になります（ただし、これらの変数のデフォルト値は true です）。
数値型の環境変数（SSE_TOOL_CALL_MAX_RETRIES、SSE_TOOL_CALL_RETRY_DELAY_BASE_MS、HTTP_TOOL_CALL_MAX_RETRIES、HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS、STDIO_TOOL_CALL_MAX_RETRIES、STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS）は、10 進整数として解析されます。解析に失敗した場合（値が数値でない場合や、変数が空または未設定の場合など）は、デフォルト値が使われます。

開発

依存関係をインストールします：

npm install
# or yarn install

サーバーをビルドします（TypeScript を build/ 内の JavaScript にコンパイルします）：

npm run build

開発モードで実行します（tsx を使用して TS を直接実行し、変更時に自動で再起動します）：

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

変更を監視して自動的に再ビルドします（tsx を使用しない場合に便利です）：

npm run watch

Docker で実行する

Dockerfile が用意されています。コンテナはデフォルトで SSE モード（build/sse.js を使用）でサーバーを実行し、必要な依存関係がすべて含まれています。TOOLS_FOLDER 環境変数のコンテナ内でのデフォルト値は /tools です。

推奨：ビルド済みイメージを使用する（GHCR から）

セットアップを簡単にするため、GitHub Container Registry のビルド済みイメージを使用することをおすすめします。イメージは 2 種類あります。

標準イメージ（軽量）：ほとんどのユーザーにとってデフォルトであり、推奨されるイメージです。MCP Proxy Server のコア機能が含まれています。
- タグ：latest、<version>（例：0.1.2）
```
# 最新の標準イメージを取得
docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

# または、特定のバージョンを取得
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:0.1.2
```
バンドルイメージ（フル機能）：このイメージには、インストール済みの MCP サーバー一式と Playwright のブラウザー依存関係が含まれています。サイズは大幅に大きくなりますが、一般的なツールをすぐに利用できます。
- タグ：<version>-bundled-mcpservers-playwright（例：0.1.2-bundled-mcpservers-playwright）または latest-bundled-mcpservers-playwright
```
# バンドル版を取得
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest-bundled-mcpservers-playwright
```
バンドルイメージには、以下のコンポーネントがインストール済みで含まれています（Docker のビルド引数を使用）。
- PIP パッケージ（PRE_INSTALLED_PIP_PACKAGES_ARG）：
  - mcp-server-time
  - markitdown-mcp
  - mcp-proxy
- NPM パッケージ（PRE_INSTALLED_NPM_PACKAGES_ARG）：
  - g-search-mcp
  - fetcher-mcp
  - playwright
  - time-mcp
  - mcp-trends-hub
  - @adenot/mcp-google-search
  - edgeone-pages-mcp
  - @modelcontextprotocol/server-filesystem
  - mcp-server-weibo
  - @variflight-ai/variflight-mcp
  - @baidumap/mcp-server-baidu-map
  - @modelcontextprotocol/inspector
- 初期化コマンド（PRE_INSTALLED_INIT_COMMAND_ARG）：
  - playwright install --with-deps chromium

ニーズに最も合ったイメージを選択してください。ほとんどのユーザーには標準イメージで十分です。バックエンドの MCP サーバーは mcp_server.json で設定できます。

次に、選択したコンテナイメージを実行します。

docker run -d \
  -p 3663:3663 \
  -e PORT=3663 \
  -e ENABLE_ADMIN_UI=true \
  -e ADMIN_USERNAME=myadmin \
  -e ADMIN_PASSWORD=yoursupersecretpassword \
  -e ALLOWED_KEYS="clientkey1" \
  -e TOOLS_FOLDER=/my/custom_tools_volume # Optional: Override default /tools for server installations
  -v ./my_config:/mcp-proxy-server/config \
  -v /path/on/host/to/tools:/my/custom_tools_volume `# Mount a volume for TOOLS_FOLDER if overridden` \
  --name mcp-proxy-server \
  ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

./my_config を、mcp_server.json と、必要に応じて tool_config.json を含むホスト側のパスに置き換えてください。コンテナは /app/config に設定ファイルがあることを想定しています。
Admin UI からサーバーのインストール先として TOOLS_FOLDER を上書きする場合は、対応するボリュームをマウントしてください（例：-v /path/on/host/for_tools:/my/custom_tools_volume）。デフォルトの /tools（Dockerfile で TOOLS_FOLDER に設定）を使用する場合は、/tools にマウントできます（例：-v /path/on/host/to/tools_default:/tools）。
特定のバージョンを取得した場合は、タグ（:latest）を適宜変更してください。
必要に応じて、-e フラグを使用して他の環境変数を設定してください。

イメージをローカルでビルドする（任意）：

docker build -t mcp-proxy-server .

(ローカルでビルドする場合は、上記の docker run コマンドで ghcr.io/... のイメージ名の代わりに mcp-proxy-server を使用してください。)

クライアントでのインストールと使用方法

このプロキシサーバーは、主に次の 2 つの方法で使用できます。

1. Stdio MCP サーバーとして： MCP クライアント（Claude Desktop など）を設定し、コマンド（build/index.js）を使ってプロキシサーバーを直接実行します。その後、プロキシは config/mcp_server.json で定義されたバックエンドサーバーに接続します。

Claude Desktop（claude_desktop_config.json）の設定例：

{
  "mcpServers": {
    "mcp-proxy": {
      "name": "MCP Proxy (Aggregator)",
      "command": "/path/to/mcp-proxy-server/build/index.js",
      "env": {
         "NODE_ENV": "production", // Optional: Set environment for the proxy itself
         "TOOLS_FOLDER": "/custom/path/for/proxy/tools" // Optional: If proxy needs to install its own backends
      }
    }
  }
}

/path/to/mcp-proxy-server/build/index.js を、このプロキシサーバープロジェクトのビルド済みエントリーポイントの実際のパスに置き換えてください。config ディレクトリがコマンドの実行場所からの相対パスで正しく配置されていることを確認してください。必要に応じて、プロキシの設定で絶対パスを使用してください。

2. SSE または Streamable HTTP MCP サーバーとして： HTTP サーバーを起動するモードでプロキシサーバーを実行します（例：npm run dev:sse または Docker コンテナ）。その後、MCP クライアントがプロキシの適切なエンドポイントに接続するように設定します。 - SSE の場合：http://localhost:3663/sse - Streamable HTTP の場合：http://localhost:3663/mcp

プロキシで認証が有効になっている場合（ALLOWED_KEYS または ALLOWED_TOKENS による）、クライアントは対応する認証情報を指定する必要があります。

認証方法（/sse および /mcp）：

API キー： クライアント設定でキーを指定します。/sse エンドポイントでは、URL クエリパラメーター ?key=... を使用できます。/sse と /mcp の両方で、X-Api-Key ヘッダーを使用できます。
Bearer トークン： クライアント設定で Authorization: Bearer <token> ヘッダーを設定します。

SSE に接続する Claude Desktop（claude_desktop_config.json）の設定例：

{
  "mcpServers": {
    "my-proxy-sse": {
      "type": "sse", // Important for clients that distinguish
      "name": "MCP Proxy (SSE)",
      // If using API Key authentication, append ?key=<your_key>
      "url": "http://localhost:3663/sse?key=clientkey1"
      // If using Bearer Token authentication, the client configuration method may vary.
      // For example, some clients might support setting custom headers:
      // "headers": {
      //   "Authorization": "Bearer your_bearer_token_1"
      // }
    }
  }
}

汎用 Streamable HTTP クライアントの設定例：

{
  "mcpServers": {
    "my-proxy-http": {
      "type": "http", // Or the client's specific designation
      "name": "MCP Proxy (Streamable HTTP)",
      "url": "http://localhost:3663/mcp",
      // Authentication headers would be configured according to the client's capabilities
      // e.g., "requestInit": { "headers": { "X-Api-Key": "clientkey1" } }
    }
  }
}

デバッグ

通信のデバッグには MCP Inspector を使用します（主に Stdio モード向けです）。

npm run inspector

このスクリプトは、インスペクターを使ってビルド済みサーバー（build/index.js）を実行します。コンソール出力に表示される URL からインスペクターの UI にアクセスしてください。SSE モードでは、標準のブラウザー開発者ツールを使用してネットワークリクエストを調査できます。

参考資料

このプロジェクトは、もともと adamwattis/mcp-proxy-server に着想を得て、リファクタリングしたものです。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

MCP Proxy Server

MCP Proxy Server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

MCP Proxy Server

✨ 主な機能

機能

プロキシによるリソースとツールの管理

✨ オプションの Web 管理 UI（ENABLE_ADMIN_UI=true）

設定

1. サーバー接続（config/mcp_server.json）

2. ツール設定（config/tool_config.json）

3. 環境変数

信頼性強化機能

1. エラーの伝播

2. SSE ツール呼び出しの再試行

3. ツール呼び出しの HTTP リクエスト再試行

4. ツール呼び出しの Stdio 接続リトライ

開発

1. エラーの伝播

2. ツール呼び出し時の SSE 接続再試行

3. ツール呼び出し時の HTTP リクエスト再試行

4. ツール呼び出しの Stdio 接続再試行

開発

Docker で実行する

クライアントでのインストールと使用方法

デバッグ

参考資料

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

✨ オプションの Web 管理 UI（`ENABLE_ADMIN_UI=true`）

1. サーバー接続（`config/mcp_server.json`）

2. ツール設定（`config/tool_config.json`）