MCP Composer

MCP Composer

MCP Composer は、すべての MCP サーバーを一元管理するゲートウェイサービスです。必要な MCP サーバーをまとめ、MCP サーバーへのアクセスを必要とする各サービス（AI エージェントやツールなど）ごとに、異なるサーバーやツールの組み合わせを設定した独立したポートを開くことができます。

主な機能

• MCP サーバーの動的管理：複数の MCP サーバーとそのツールへの接続を動的に管理し、サービスをその場で有効化または無効化できます。
• 統合 MCP エンドポイント：管理対象の MCP サーバーが持つすべての機能にアクセスできる単一の Streamable HTTP エンドポイント（最新の MCP プロトコル 2026-07-28 とそれ以前のバージョンをサポート）を公開します。Streamable HTTP にまだ対応していないクライアント向けに、従来の SSE エンドポイントも利用できます。
• 複数の動的エンドポイント：さまざまな AI エージェントや AI ツールに対応するため、複数のゲートウェイエンドポイントを動的に作成・削除できます。
• インターフェースの個別設定：各ゲートウェイは、MCP サーバーとツールの組み合わせを個別に管理し、カスタマイズされたサービスを提供できます。

システムアーキテクチャ

主な用語

• MCP クライアント：Cursor、n8n などの外部ツール、AI エージェント、AI ワークフローです。
• Gateway[A/B]：ServerKit にバインドされ、Composer によって管理される MCP サーバーの実装で、MCP クライアントとの接続を処理します。
• Server Kit：下流 MCP サーバーに関する情報と、各サーバーで有効にするツールを管理・制御します。
• Downstream Controller：下流 MCP サーバーへの接続を制御・管理します。
• Downstream MCP Server：下流 MCP サーバーに接続する内部オブジェクトです。下流 MCP サーバーと連携する内部 MCP クライアントとして実装されています。
• MCP サーバー：https://github.com/modelcontextprotocol/servers などの外部 MCP サーバーサービスです。
• Composer：ゲートウェイ、Server Kit、Downstream Controller を制御・連携するための API を提供します。

要件

• Python >= 3.12
• uv：高速な Python パッケージインストーラーおよびマネージャーです。

インストール

方法 1：

1. リポジトリをクローンする：

   git clone https://github.com/htkuan/mcp-composer
   cd mcp-composer
   

2. 依存関係をインストールする： uv を使用して、プロジェクトの依存関係を同期します。

   make install
   # or directly use uv
   # uv sync
   

方法 2：

ローカルの Python/uv 環境の代わりに Docker Compose を使用します。詳しくはDocker Compose での実行をご覧ください。

設定

アプリケーションを実行する前に、接続先の MCP サーバーを設定する必要があります。

1. サンプル設定ファイルをコピーします。

   cp mcp_servers.example.json mcp_servers.json
   

2. mcp_servers.json を編集し、接続する MCP サーバーの詳細を入力します。

   • ローカルサーバーでは command / args / env（stdio トランスポート）を使用します。
   • リモートサーバーでは url を使用します。デフォルトでは Streamable HTTP トランスポートが最初に試され、失敗した場合は従来の SSE トランスポートにフォールバックします。特定のトランスポートを強制するには、"type": "http" または "type": "sse" を設定します。
   • 各下流サーバーがサポートする最新のプロトコルバージョンが自動的にネゴシエートされるため、古い MCP SDK で構築されたサーバーも引き続き動作します。

3. 環境変数を設定します。

   cp .env.example .env
   

4. .env ファイルを編集し、次の設定を行います。

   • HOST：サーバーのホストアドレス（デフォルト：0.0.0.0）
   • PORT：サーバーのポート（デフォルト：8000）
   • MCP_COMPOSER_PROXY_URL：MCP Composer のプロキシ URL（デフォルト：http://localhost:8000）
   • MCP_SERVERS_CONFIG_PATH：MCP サーバー設定ファイルのパス（デフォルト：./mcp_servers.json）

実行

uv を使って FastAPI アプリケーションを実行します。

make run
# or directly use uv
# uv run src/main.py

サービスの起動後、ブラウザーで API ドキュメントを開いて API を利用できます（通常は http://127.0.0.1:8000/docs です）。

各ゲートウェイは 2 つの MCP エンドポイントを公開します（デフォルトのゲートウェイ名は composer です）。

• Streamable HTTP（推奨）：http://127.0.0.1:8000/mcp/{gateway_name}/mcp
• SSE（レガシー）：http://127.0.0.1:8000/mcp/{gateway_name}/sse

Docker Compose での実行

Docker イメージには Python、uv/uvx、Node.js/npx、Docker CLI が含まれているため、uvx、npx、または docker run で起動する stdio サーバーはコンテナー内で動作します。

1. 設定の説明に従って mcp_servers.json を作成します。プロジェクトディレクトリはコンテナーにマウントされるため、ファイルは /app/mcp_servers.json から読み込まれます。

2. サービスをビルドして起動します。

   make run-docker
   # or directly use docker compose
   # docker compose up -d --build
   

   新しい変更を取得した後は、docker compose up -d --build を実行してイメージを再ビルドしてください。

3. ステータスとログを確認します。

   docker compose ps                    # STATUS shows "(healthy)" once the service is ready
   docker compose logs -f mcp-composer  # shows which downstream servers connected
   

   UI、API ドキュメント、ゲートウェイエンドポイントは、実行と同じ URL で利用できます。

4. サービスを停止します。

   docker compose down
   

注意事項：

• コードの変更：src/ は作業コピーからマウントされているため、コードまたは mcp_servers.json の変更を反映するには、再ビルドせずに docker compose restart を実行してください。
• マシン上のサービスへの接続：コンテナー内では、localhost はコンテナー自体を指します。代わりに host.docker.internal を使用してください。例："url": "http://host.docker.internal:8001/mcp"。これは docker run エントリーで起動するコンテナーにも当てはまります。Linux では、docker-compose.yml のサービスに extra_hosts: ["host.docker.internal:host-gateway"] を追加してください。
• Docker ベースの MCP サーバー：ホストの Docker ソケットがマウントされるため、"command": "docker" エントリーはホスト上に兄弟コンテナーを起動します。これにより、コンテナーから Docker デーモンへ完全にアクセスできます。
• 環境変数：MCP_SERVERS_CONFIG_PATH と MCP_COMPOSER_PROXY_URL は docker-compose.yml で設定され、.env より優先されます。公開ポートは 8000:8000 に固定されています。PORT を変更する場合は、ports も更新してください。

開発

このプロジェクトには、一般的な開発タスクを簡単に実行できる Makefile が含まれています。

• 依存関係のインストール：make install
• コードのフォーマットとチェック：make format（Ruff を使用）
• アプリケーションの実行：make run
• Docker Compose での実行：make run-docker

コントリビューション

このプロジェクトへのコントリビューションを歓迎します。標準的な GitHub の Fork & Pull Request ワークフローに従ってください。Pull Request を提出する前に、議論のための Issue を作成することをおすすめします。