universal-connector-mcp

なぜ新たに作るのか？

多くの「ユニバーサル API」MCP サーバーが対応しているのは REST／OpenAPI のみです。このプロジェクトは、次の 3 つの特徴を軸に構築されています。

1. 真にユニバーサル - プラグイン可能な仕様アダプター（OpenAPI、GraphQL、gRPC、SOAP）を備えた、正規化された Operation モデルを採用しています。ツールや実行機能は、操作の生成元プロトコルを意識する必要がありません。
2. セキュリティ優先／ローカル優先 - AgentBaiting / FakeGit キャンペーンのようなサプライチェーン攻撃への直接的な対策です。外部へのリクエストは許可リストで制限され、シークレットがログに記録されることはなく、レスポンスのサイズには上限が設けられ、すべての呼び出しが監査ログに記録されます。任意のコード実行、バイナリのダウンロード、テレメトリーはありません。
3. コンテキスト効率を重視した設計 - フィールド単位のレスポンスフィルタリング、連続実行と並列実行、レスポンスキャッシュにより、ワークフロー全体を 1 回のツール呼び出しで実行でき、レスポンスを小さく保てます。

仕組み

エージェントは API のツールを一度に何百個も読み込むのではなく（Stripe のような大規模 API ではコンテキストウィンドウを圧迫します）、ファイルシステムのように API を探索します。操作を検索し、必要なものを調べてから実行します。

flowchart TD
    Agent["AI Agent"] -->|"MCP stdio"| Server["FastMCP Server"]
    Server --> Tools["Meta-tools"]
    Tools --> Registry["Operation Registry (normalized)"]
    Adapters["Spec Adapters"] --> Registry
    Tools --> Guard["Security Guard"]
    Guard --> Executor["Protocol Executors"]
    Executor --> Auth["Auth Manager"]
    Executor --> UpstreamAPI["Upstream API"]

メタツール

ステップ数（およびトークン数）を削減

API ごとの MCP サーバーでは、呼び出しごとにツールとの往復が必要となり、そのたびに完全な JSON ペイロードがエージェントのコンテキストに返されますが、このサーバーではワークフロー全体をまとめて実行できます。

• extract - execute(..., extract=["items.*.name", "total_count"]) を使うと、数キロバイトに及ぶレスポンス全体ではなく、指定したフィールドだけが返されます。* は配列の各要素に展開されます。
• チェーン実行 - execute_chained は ${save_as.path} 形式の参照を使って、あるステップの結果を後続ステップのパラメーターに渡します。N 回のツール呼び出しが 1 回で済みます。
• 並列グループ - ステップをネストしたリストにすると、並行して実行されるため、「3 つの API に問い合わせて結果を統合する」処理も 1 回の呼び出しで済みます。

execute_chained(steps=[
  [
    {"operation_id": "github.repos_get", "params": {"owner": "o", "repo": "r"},
     "save_as": "gh", "extract": ["stargazers_count"]},
    {"operation_id": "open_meteo.get_v1_forecast", "params": {"latitude": 52.5, "longitude": 13.4},
     "save_as": "weather", "extract": ["current_weather.temperature"]}
  ],
  {"operation_id": "github.issues_list_for_repo",
   "params": {"owner": "o", "repo": "r"}, "extract": ["*.title"]}
])

• レスポンスキャッシュ - 成功した GET／クエリの結果は UCMCP_CACHE_TTL 秒間（デフォルトは 60 秒）キャッシュされるため、繰り返しの検索も即座に無料で実行できます。キャッシュを迂回するには fresh: true を渡します。成功した変更操作では、その API のキャッシュ済み読み取り結果が無効化されます。

組み込み API カタログ

仕様 URL を探し回る必要はありません。search_catalog は 2 つの情報源を検索します。

1. 検証済みの無料／人気 API を集めた厳選リスト：GitHub、GitLab、Stripe、OpenAI、Wikipedia、Open-Meteo（天気、キー不要）、国情報を扱う GraphQL API、httpbin、Swagger Petstore。各項目には、動作する仕様 URL、ベース URL の上書き設定、認証に関するヒント（例：「任意の GITHUB_TOKEN」）が含まれています。
2. APIs.guru ディレクトリ：コミュニティによってインデックス化された 2500 件以上の OpenAPI 仕様（Google、AWS、Microsoft、Twilio、NASA など）。セッションごとに 1 回取得され、ローカルで検索されます。

search_catalog(query="weather forecast")
  -> [{"name": "open_meteo", "spec": "https://...forecast.yml", "base_url": "https://api.open-meteo.com", ...}]
load_api(spec="https://...forecast.yml", name="open_meteo", base_url="https://api.open-meteo.com")
execute(operation_id="open_meteo.get_v1_forecast", params={"latitude": 52.52, "longitude": 13.41, "hourly": "temperature_2m"})

カタログは発見専用です。返すのは仕様 URL のみで、カタログ自体が何かを読み込んだり実行したりすることはありません。そのため、読み込むすべてのものにセキュリティガードが引き続き適用されます。

インストール

サーバーは uvx を使って、どの MCP ホストでも実行できます。手動インストールは不要で、パッケージは PyPI から自動的に取得されます（GraphQL／gRPC／SOAP のサポートを有効にするには [all] を追加します）。

{
  "mcpServers": {
    "universal-connector": {
      "command": "uvx",
      "args": ["universal-connector-mcp"],
      "env": { "UCMCP_ALLOWED_HOSTS": "api.github.com" }
    }
  }
}

ソースからインストールする場合（開発用）：pip install -e ".[all,dev]" を実行し、代わりに "command": "universal-connector-mcp" を使用します。追加機能：graphql、grpc、soap、keyring、all、dev。コアのインストールでサポートされるのは OpenAPI／REST のみです。

Cursor

上のバッジを使ってワンクリックで追加するか、プロジェクト内の .cursor/mcp.json（チームと共有）または ~/.cursor/mcp.json（個人用、すべてのプロジェクト）に JSON ブロックを追加します。認証情報を含む完全な設定については、examples/mcp.json を参照してください。

Claude Desktop

同じ mcpServers ブロックを claude_desktop_config.json に追加します（Settings > Developer > Edit Config）。

Claude Code

claude mcp add universal-connector -- uvx universal-connector-mcp

VS Code（Copilot）

.vscode/mcp.json の "servers" の下にサーバーを追加します。

{
  "servers": {
    "universal-connector": { "command": "uvx", "args": ["universal-connector-mcp"] }
  }
}

Windsurf／Cline／その他

主要な MCP ホストはすべて、それぞれの設定ファイル（~/.codeium/windsurf/mcp_config.json、Cline の MCP 設定など）で、上記と同じ mcpServers ブロックを使用できます。

このサーバーをユーザーのためにインストールする AI エージェントは、llms-install.md に従ってください。

API の事前読み込み

UCMCP_APIS_CONFIG に YAML ファイルを指定すると、起動時に API を自動で読み込めます。詳しくは examples/apis.example.yaml を参照してください。

チャットから API を管理する

API を管理するために設定ファイルを編集する必要はありません。エージェントに指示するだけです。

• 「Stripe API に接続して」 — エージェントがカタログから見つけて読み込みます。
• 「接続されている API は？」 — list_apis で確認できます。
• 「GitHub を忘れて」 — unload_api で削除されます（記憶された状態からも削除されます）。

API に認証情報が必要な場合、load_api は設定すべき環境変数（例：STRIPE_API_KEY）と、すでに設定されているかどうかをエージェントに正確に伝えます。エージェントはコピーして貼り付けられる手順を提示するため、MCP 設定の env ブロックに変数を追加して再起動してください。シークレットをチャットに入力する必要はありません。

セッションの永続化

サーバーは、読み込んだ API（仕様の場所のみ。認証情報やレスポンスデータは含みません）を UCMCP_STATE_FILE に記憶し、次回の起動時に自動的に復元するため、エージェントは前回の続きから作業できます。無効にするには UCMCP_STATE_FILE=off を設定します。

サポート対象のプロトコル

読み込まれた各操作には、<api>.<operation> の形式で名前空間付き ID が割り当てられます（例：github.repos_get）。

セッションの例

その他の使用例（天気、認証付き GitHub、GraphQL、複数 API の並列ワークフロー、内部 API）：docs/EXAMPLES.md

search_catalog(query="github")
load_api(spec="https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", name="github")
search_operations(query="list repositories for user", api="github")
get_operation(operation_id="github.repos_list_for_user")
execute(operation_id="github.repos_list_for_user", params={"username": "torvalds"},
        extract=["*.name", "*.stargazers_count"])

フィールド選択を使った GraphQL：

load_api(spec="https://countries.trevorblades.com/", protocol="graphql", name="countries")
execute(operation_id="countries.country", params={"code": "US", "fields": "name capital currency"})

連鎖（1 つ目の結果を次に渡します。手順をネストしたリストで囲むと、並列実行できます）：

execute_chained(steps=[
  {"operation_id": "github.repos_list_for_user", "params": {"username": "torvalds"}, "save_as": "repos"},
  {"operation_id": "github.repos_get", "params": {"owner": "torvalds", "repo": "${repos.data.0.name}"},
   "extract": ["description", "stargazers_count"]}
])

設定

すべての設定は、UCMCP_ をプレフィックスとする環境変数です。

認証情報は、慣例に従って <API_NAME>_TOKEN、<API_NAME>_API_KEY、<API_NAME>_CLIENT_ID / <API_NAME>_CLIENT_SECRET（OAuth2 クライアントクレデンシャル）などから検索されます。

開発

pip install -e ".[all,dev]"
pytest          # run the test suite
ruff check .    # lint

テストスイート（60 件以上のテスト）と lint は、プッシュのたびに CI で Ubuntu および Windows 上の Python 3.10 と 3.12 を使って実行されます（.github/workflows/ci.yml）。v* のタグ付けにより、信頼された公開を通じて PyPI へのビルドと公開が行われます（.github/workflows/release.yml）。

コントリビューションを歓迎します。CONTRIBUTING.md をご覧ください。セキュリティに関する報告は非公開の報告窓口からお寄せください。

リリースは自動化されています。v* のタグ付けにより、信頼された公開を通じて PyPI に公開されます（docs/RELEASING.md をご覧ください）。

セキュリティモデル

• 送信先の許可リスト - デフォルトでは、明示的に読み込まれた仕様のホストのみ接続できます。UCMCP_ALLOWED_HOSTS / UCMCP_DENIED_HOSTS で範囲を拡張または制限できます。
• SSRF 対策 - プライベート、ループバック、リンクローカル、予約済み、またはクラウドメタデータのアドレスに解決されるリクエストはブロックされます（仕様の取得、GraphQL イントロスペクション、SOAP のインポートを含みます）。リダイレクトの各段階で再検証されます。内部アドレスへの接続には、明示的な UCMCP_ALLOWED_HOSTS のエントリーが必要です。
• シークレットの取り扱い - 認証情報は環境変数または OS のキーチェーンから取得され、リクエスト時にのみ挿入されます。監査ログとエラーからは秘匿情報が伏せられます。
• レスポンスの上限 - コンテキストウィンドウを保護するため、レスポンスは設定可能なバイト数の上限で切り詰められます。
• 監査ログ - すべての送信呼び出しのメソッド、ホスト、パス、ステータスが記録されます（シークレットや本文は記録されません）。

ライセンス

MIT