MCP SSE Proxy Server

MCP SSE Proxy サーバー

MCP SSE Proxy サーバーは、Server-Sent Events（SSE）ベースのModel Context Protocol（MCP）プロキシサーバーです。標準のMCPプロトコルを使用して、MCPサーバーをリモートで実行できます。共有セッションモードと独立セッションモードの両方に対応しています。

Model Context Protocol（MCP）は、アプリケーションがLLMにコンテキストを提供する方法を標準化するオープンプロトコルです。MCPは、AIアプリケーション向けのUSB-Cポートのようなものと考えてください。USB-Cがデバイスをさまざまな周辺機器やアクセサリーに接続する標準的な方法を提供するように、MCPはAIモデルをさまざまなデータソースやツールに接続する標準的な方法を提供します。

MCPの詳細については、以下をご覧ください。

• MCPドキュメント（英語）
• MCPドキュメント（中文）
• MCPサーバーギャラリー - さまざまなMCPサーバーを見つけてご覧ください

中文文档

どのような問題を解決しますか？

このプロジェクトでは、次のことができます。

• 標準のMCPプロトコルを使用して、あらゆるMCPサーバーをリモートで起動し、操作する
• SSEを通じて安定した長時間接続を維持する
• 複数のクライアントで1つのMCPセッションを共有するか、独立したセッションを維持する
• リクエストパラメーターを通じてサーバー環境を動的に設定する
• NPXとUVXを使用してSTDIOプロセスをすばやくデプロイする

システムアーキテクチャ

機能

• サーバーからのプッシュ通知に対応したSSE長時間接続
• JSON-RPC 2.0メッセージ形式に対応
• 共有セッションモードと独立セッションモードの両方に対応
• リクエストパラメーターを通じた動的なセッション環境設定
• 接続の自動維持（30秒間隔のハートビート）
• 包括的なエラー処理とログ記録
• NPXおよびUVXによるSTDIOプロセスのデプロイに標準対応

統合とカスタマイズ

カスタムDockerイメージ

MCP SSE Proxy サーバーは、さまざまなカスタムDockerイメージに高い柔軟性で統合できるように設計されています。この柔軟性により、さまざまなユースケースに対応する専用環境を作成できます。

• ブラウザー自動化：ブラウザーベースのMCPサーバー向けにChrome/Chromiumを統合
• データベース操作：データ操作用MCPサーバー向けに特定のデータベースを同梱
• 開発ツール：コード関連のMCPサーバー向けに開発ツールをパッケージ化
• AI/MLツール：機械学習用MCPサーバー向けにAI/MLライブラリを同梱

高度なルーティング

デフォルト設定では、環境変数を通じてMCPサーバーコマンドを読み込みますが、次の方法で機能を拡張できます。

1. 複数サーバーの統合：設定ファイルを通じて複数のMCPサーバーを設定する
2. 動的ルーティング：SSE接続にルーティングフィールドを追加し、異なるMCPサーバーにトラフィックを振り分ける
3. カスタムルーター：このベース実装を拡張して、独自のMCPルータープロジェクトを構築する

この柔軟性により、次のことが可能になります。

• 専用のMCPサーバークラスターを作成する
• 複数のサーバー間で負荷分散を実装する
• ニーズに基づいてカスタムルーティングロジックを設計する
• 階層型MCPサーバーアーキテクチャを構築する

設定

環境変数

• SHARED_SESSION：セッションモードを制御します

  • true：共有セッションモード（デフォルト）。すべてのクライアントが1つのMCPセッションを共有します
  • false：独立セッションモード。クライアントごとに個別のMCPセッションを作成します

• AUTH_KEY：サーバーアクセスキー

  • 設定した場合、すべてのリクエストでこのキーを指定する必要があります
  • URLパラメーター auth_key を通じて渡します

• MCP_SERVER_CONFIG：MCPサーバーの設定 例：

  # Run Node.js-based MCP server using NPX
  MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-filesystem ."
  
  # Run Python-based MCP server using UVX
  MCP_SERVER_CONFIG="uvx mcp-server-fetch"
  

動的な設定

独立セッションモード（SHARED_SESSION=false）では、SSE 接続ごとに新しい MCP サーバープロセスが起動します。URL パラメーターを使って、各セッションの環境変数を動的に設定できます。

GET /sse?auth_key=xxx&[CUSTOM_ENV]=value

この仕組みは、ユーザーごとの認証情報が必要なシナリオで特に便利です。たとえば、GitHub MCP サーバーをデプロイする場合、ユーザーごとに自分の Personal Access Token を使用できます。

1. サーバーをデプロイするときに、ベースコマンドを設定します。

export MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-github"

2. 接続時に、ユーザーが URL 経由でトークンを指定します。

GET /sse?auth_key=xxx&GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx

この方法なら、MCP プロキシサーバーを 1 台デプロイするだけで複数のユーザーにサービスを提供でき、各ユーザーは自分の GitHub 認証情報を使用できます。その他にサポートされている環境変数の設定は次のとおりです。

• 全般的な設定：

  • NODE_ENV：Node.js 環境（development／production）
  • DEBUG：デバッグログレベル

• サーバー固有の設定：

  • GitHub MCP Server：GITHUB_PERSONAL_ACCESS_TOKEN
  • Filesystem MCP Server：ROOT_DIR
  • その他のサーバー固有の環境変数

注：URL パラメーターの環境変数は、サーバーのデフォルト設定より優先されます。

API エンドポイント

SSE 接続

GET /sse?auth_key=xxx

接続が正常に確立されると、サーバーはメッセージエンドポイントの URL を返します。

event: endpoint
data: /messages?session_id=<session_id>

メッセージの送信

POST /messages?session_id=<session_id>
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "method": "method_name",
    "params": {},
    "id": 1
}

サポートされているメソッド

• initialize：セッションを初期化します
• tools/list：利用可能なツールを一覧表示します
• tools/call：ツールを呼び出します
• prompts/list：利用可能なプロンプトを一覧表示します
• prompts/get：プロンプトを取得します
• resources/list：リソースを一覧表示します
• resources/templates/list：リソーステンプレートを一覧表示します
• resources/read：リソースを読み込みます
• resources/subscribe：リソースを購読します
• resources/unsubscribe：リソースの購読を解除します

サーバーの実行

Python を使用する場合

# Set environment variables
export AUTH_KEY=your_key
export SHARED_SESSION=true  # or false

# Start the server
python main.py

サーバーはデフォルトで 0.0.0.0:8000 で起動します。

Docker を使用する場合

1. Docker イメージをプルします。

docker pull codefriday123/mcpproxy:1.0

2. コンテナーを実行します。

docker run -d \
  -p 8000:8000 \
  -e AUTH_KEY=your_key \
  -e SHARED_SESSION=true \
  -e MCP_SERVER_CONFIG="npx -y @modelcontextprotocol/server-filesystem ." \
  codefriday123/mcpproxy:1.0

環境変数：

• AUTH_KEY：サーバーアクセスキー（必須）
• SHARED_SESSION：セッションモード（デフォルト：true）
• MCP_SERVER_CONFIG：MCP サーバー設定コマンド

サーバーは http://localhost:8000 で利用できます。

Alipay Cloud Run を使用する場合

Alipay Cloud Run（新人可免费使用容器资源）にサーバーをデプロイすることもできます。

1. Cloud Run で新しいサービスを作成します

2. 次の設定でサービスを構成します：

   • イメージ：codefriday123/mcpproxy:1.0
   • ポート：8000
   • 環境変数：
     • AUTH_KEY：サーバーアクセスキー
     • SHARED_SESSION：true/false
     • MCP_SERVER_CONFIG：MCP サーバー設定

3. サービスをデプロイします

サーバーは、指定された Cloud Run エンドポイントで利用できます。

ログ

サーバーは Python の logging モジュールを使用して、次のような詳細なログを記録します。

• 環境変数の情報
• 接続の確立と終了
• メッセージ処理
• エラーと例外

エラー処理

サーバーは標準の JSON-RPC 2.0 エラーレスポンス形式を使用します。

{
    "jsonrpc": "2.0",
    "error": {
        "code": error_code,
        "message": "error message"
    },
    "id": null
}

主なエラーコード：

• -32700：解析エラー
• -32600：無効なリクエスト
• -32601：メソッドが見つかりません
• -32602：無効なパラメーター
• -32603：内部エラー
• -32000：サーバーエラー

使用例

Python クライアント

公式の MCP Python クライアントを使用して、デプロイ済みの MCP サーバーに接続できます。

import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, LoggingLevel
from mcp.client.sse import sse_client

class MCPClient:
    def __init__(self):
        self.session: Optional[ClientSession] = None
        self._streams_context = None
        self._session_context = None
        self.exit_stack = AsyncExitStack()

    async def connect_to_sse_server(self, server_url: str):
        """Connect to an MCP server running SSE transport"""
        try:
            print(f"Connecting to {server_url}...")
            self._streams_context = sse_client(url=server_url)
            streams = await self._streams_context.__aenter__()
            self._session_context = ClientSession(*streams)
            self.session = await self._session_context.__aenter__()
            
            try:
                await asyncio.wait_for(self.session.initialize(), timeout=30.0)
                print("Session initialized successfully")
            except asyncio.TimeoutError:
                print("Session initialization timed out, but will continue")

        except Exception as e:
            print(f"Connection error: {e}")
            await self.cleanup()
            raise

    async def cleanup(self):
        """Properly clean up session and streams"""
        try:
            if hasattr(self, '_session_context') and self._session_context:
                await self._session_context.__aexit__(None, None, None)
            if hasattr(self, '_streams_context') and self._streams_context:
                await self._streams_context.__aexit__(None, None, None)
        except Exception as e:
            print(f"Cleanup error: {e}")

async def main():
    client = MCPClient()
    try:
        await client.connect_to_sse_server('http://your-server:8000/sse?auth_key=your_auth_key')
        response = await asyncio.wait_for(client.session.list_tools(), timeout=10.0)
        print(f"Available tools: {[tool.name for tool in response.tools]}")
    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.cleanup()

if __name__ == "__main__":
    asyncio.run(main())

### Cursor Integration

You can also integrate with [Cursor](https://docs.cursor.com/context/model-context-protocol) by adding the server to Cursor's MCP configuration:

```json
{
  "mcpServers": {
    "server-name": {
      "url": "http://your-server:8000/sse?auth_key=your_auth_key",
      "env": {
      }
    }
  }
}

次のいずれかの場所にこの設定を記述してください。

• プロジェクト固有のアクセスの場合は、プロジェクトディレクトリ内の .cursor/mcp.json
• グローバルアクセスの場合は、ホームディレクトリ内の ~/.cursor/mcp.json

ライセンス

MIT ライセンス

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

ロードマップ

現在の機能

• 基本的な MCP サーバープロキシ機能
• SSE トランスポートのサポート
• 共有セッションモードと独立セッションモード
• 動的な環境設定
• Cursor およびその他の MCP クライアントとの連携

今後の計画

• ステートレスアーキテクチャ

  • ステートレス運用向けのツール専用モード
  • セッション管理を必要としないHTTPベースのツール実行
  • デプロイとスケーリングの簡素化
  • リソースのオーバーヘッド削減
  • 信頼性と保守性の向上

• エージェントサンドボックス

  • MCP エージェントを実行するための分離された環境の作成
  • リソース制限とモニタリング
  • 信頼できないエージェント向けのセキュリティサンドボックス
  • エージェント実行のパフォーマンス最適化
  • ストリーミング可能なHTTPのサポート
    • ストリーミング可能なHTTPプロトコルとの前方互換性
    • ハイブリッドモード：柔軟性を高めるSSE + HTTP
    • プロトコルネゴシエーションとフォールバックの仕組み
    • ストリーミングパフォーマンスの最適化

• エージェントルーター

  • 複数のMCP サーバー間のインテリジェントなルーティング
  • 負荷分散とフェイルオーバー
  • リクエスト／レスポンスの変換
  • プロトコルバージョンの互換性処理
  • 高度なルーティングルールとポリシー

• ベストプラクティス

  • さまざまなシナリオに対応するデプロイガイド
  • セキュリティに関する推奨事項
  • パフォーマンス最適化のヒント
  • モニタリングとロギングのベストプラクティス
  • さまざまなMCP サーバーとの統合パターン

最新情報や新機能にご期待ください！