MCP Facade

MCP Facade

複数の MCP（Machine Conversation Protocol）サーバーを管理し、やり取りするための統一インターフェースを提供する、高機能なファサードサービスです。エージェントがさまざまな MCP サーバーと通信するための単一のエントリーポイントとして機能し、堅牢な認証とアクセス制御を提供します。

目次

• 機能
• インストール
• 設定
• API ドキュメント
  • サーバー管理
  • ツール管理
  • アクセス制御
  • MCP プロトコル
• 認証
• 使用例

機能

• 統合アクセスポイント：複数の MCP サーバー向けの単一インターフェース
• サーバー管理：複数の MCP サーバーの登録、更新、管理
• ツール管理：登録済みのすべてのサーバーでツールを検出し、やり取り
• 認証：きめ細かなアクセス制御を備えた JWT ベースの認証
• アクセスルール：ツール単位で設定可能なアクセスルール
• ヘルスモニタリング：組み込みのヘルスチェックエンドポイント
• データベースバックエンド：サーバー設定とアクセスルールの保存に PostgreSQL を使用

ローカルで実行する

MCP サーバーを実行する（例）

注：MCP サーバーをすでにお持ちの場合は、この手順をスキップできます。

cd mcp-facade/mcp-servers

uv sync
source .venv/bin/activate
uv pip install -e .

# start mcp servers
uv run src/mcp_servers/main.py

MCP ファサードを実行する

# Clone the repository
git clone https://github.com/yourusername/mcp-facade.git
cd mcp-facade/mcp-facade

# Install dependencies
pnpm i

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the service
pnpm dev

設定を追加する

# add echo 
curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "echo",
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

# add math
curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "math",
    "url": "http://127.0.0.1:3003/math/mcp"
  }'

oap-langgraph-tools-agent と併用する

# clone fork (with disabled auth)
git clone [email protected]:DmitryBe/oap-langgraph-tools-agent.git
cd oap-langgraph-tools-agent

# install deps 
uv sync
source .venv/bin/activate

# run langfraph server locally
langgraph dev

# open url
open https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

# create assistant with configuration
MCPConfig
    url: http://localhost:3000/api
    tools: echo, add, subtract, multiply, divide

# start a thread by asking somehting like: compute 2 * 5 - 3

API ドキュメント

サーバー管理

以下のエンドポイントを使用して、MCP サーバーを管理できます。

すべてのサーバーを一覧表示する

curl http://localhost:3001/api/mcp/servers | jq .

名前でサーバーを取得する

curl http://localhost:3001/api/mcp/servers/echo | jq .

サーバーを作成する

curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "echo",
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

サーバーを更新する

curl -X PUT http://localhost:3001/api/mcp/servers/echo \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

サーバーを削除する

curl -X DELETE http://localhost:3001/api/mcp/servers/echo

ツール管理

使用可能なツールを一覧表示する

curl http://localhost:3000/api/mcp/tools | jq .

ツールを呼び出す

curl -N -X POST http://localhost:3000/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello, world!"
      }
    }
  }'

アクセス制御

このサービスは、ツール単位できめ細かなアクセス制御に対応しています。アクセスルールは、次の種類を使って設定できます。

• WILDCARD：すべてのユーザーにアクセスを許可する
• SCOPE：特定の OAuth スコープを必須とする
• USER_ID：特定のユーザー ID に制限する

すべてのアクセスルールを一覧表示する

curl http://localhost:3001/api/access-rules | jq .

ツールのルールを取得する

curl http://localhost:3001/api/access-rules/by-tool/echo | jq .

アクセスルールを作成する

# Allow everyone
curl -X POST http://localhost:3001/api/access-rules/by-tool/echo \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "WILDCARD", "value": null}'

# Require specific scope
curl -X POST http://localhost:3001/api/access-rules/by-tool/add \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "SCOPE", "value": "openid"}'

アクセスルールを更新する

curl -X PUT http://localhost:3001/api/access-rules/2 \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "USER_ID", "value": "1,2,3"}'

アクセスルールを削除する

curl -X DELETE http://localhost:3001/api/access-rules/3

MCP プロトコル

このサービスは、ツールとのやり取りに MCP プロトコルを実装しています。一般的な操作を以下に示します。

接続を初期化する

curl -N -X POST http://localhost:3001/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      }
    }
  }'

ツールを一覧表示する

curl -N -X POST http://localhost:3000/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }' | jq -R 'select(startswith("data: ")) | .[6:] | fromjson'

サーバーに ping を送信する

curl -N -X POST http://localhost:3001/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "ping"
  }' | jq -R 'select(startswith("data: ")) | .[6:] | fromjson'

認証

このサービスは認証に JWT（JSON Web Token）を使用します。認証が必要なリクエストでは、JWT トークンを Authorization ヘッダーに含めてください。

curl -H "Authorization: Bearer your.jwt.token" http://localhost:3001/api/mcp/tools

コントリビューション

コントリビューションを歓迎します。Pull Request をお気軽にご提出ください。