mcp-api-connect

mcp-api-connect™

ペイロードを渡せば、あらゆる API に接続できます。 mcp-api-connect は、プロトコルや認証方式に依存しないコネクターエンジンです。対象サービス（URL、プロトコル、認証方式、リクエスト／レスポンスの形式）を一度記述すれば、正規化されたペイロードを送信して、正規化されたレスポンスを受け取れます。対象が REST／JSON API でも、レガシーな SOAP サービスでも、API キー、Basic 認証、Bearer トークン、OAuth2 クライアントクレデンシャルで保護されたサービスでも利用できます。

同じコアエンジンを基盤とする以下の 3 つの形態で提供されているため、用途に合わせて利用できます。

• Python ライブラリ — pip install mcp-api-connect を実行し、MCPAPIConnectEngine を直接呼び出します。サーバーは不要です。
• スタンドアロン HTTP API — pip install mcp-api-connect[api] を実行し、mcp-api-connect-api を起動して、/invoke に POST します。
• MCP サーバー — pip install mcp-api-connect[mcp] を実行し、mcp-api-connect を起動します。任意の MCP クライアント（Claude など）から接続すると、エージェントが登録済みのコネクターや、その場で指定した任意のサービスをツールとして呼び出せます。

その理由

統合プロジェクトでは、毎回同じ仕組みを作り直しています。REST クライアントや SOAP クライアント、サービスごとの認証フロー、コードベース全体に散在する場当たり的なリクエスト／レスポンスのマッピングなどです。mcp-api-connect は、それらを 1 つの宣言的な仕様（InvokeSpec）と 1 つの実行エンジンに集約します。そのため、新しい対象サービスの追加は、コードではなく設定で行えます。

クイックスタート（ライブラリ）

pip install mcp-api-connect

import asyncio
from mcp_api_connect import MCPAPIConnectEngine, InvokeSpec, Target, AuthSpec, AuthType, RequestFormat, ResponseFormat

spec = InvokeSpec(
    target=Target(base_url="https://api.example.com"),
    auth=AuthSpec(type=AuthType.API_KEY, config={"api_key": "secret", "header_name": "X-API-Key"}),
    request_format=RequestFormat(method="POST", path="/v1/orders", content_type="json"),
    response_format=ResponseFormat(content_type="json"),
)

async def main():
    async with MCPAPIConnectEngine() as engine:
        result = await engine.invoke(spec, {"customer": "jane"})
        print(result.success, result.data)

asyncio.run(main())

クイックスタート（HTTP API）

pip install "mcp-api-connect[api]"
mcp-api-connect-api   # serves on :8000, interactive docs at /docs

curl -X POST http://localhost:8000/invoke -H 'content-type: application/json' -d '{
  "spec": {
    "target": {"base_url": "https://api.example.com"},
    "auth": {"type": "api_key", "config": {"api_key": "secret"}},
    "request_format": {"method": "POST", "path": "/v1/orders"},
    "response_format": {"content_type": "json"}
  },
  "payload": {"customer": "jane"}
}'

再利用可能なコネクターを一度登録すれば、名前で呼び出せます。

curl -X POST http://localhost:8000/connectors -d '{"name": "orders-api", "spec": {...}}'
curl -X POST http://localhost:8000/connectors/orders-api/invoke -d '{"customer": "jane"}'

クイックスタート（MCP）

pip install "mcp-api-connect[mcp]"

{
  "mcpServers": {
    "mcp-api-connect": { "command": "/path/to/.venv/bin/mcp-api-connect" }
  }
}

または、コンテナー内で実行します（stdio トランスポート）。

docker build -t mcp-api-connect .
docker run --rm -i mcp-api-connect

次のツールを公開します：invoke（ステートレスな単発呼び出し）、register_connector、list_connectors、invoke_connector（名前で呼び出し）、delete_connector。エージェントは「Salesforce API」用のコネクターを一度登録すれば、その後は「このペイロードで呼び出して」と指示するだけで済みます。

➜ Claude Desktop／Claude Code／Cursor の完全なセットアップ手順、永続化、セキュリティに関する注意事項、実例については、docs/mcp-integration.md をご覧ください。

主な概念

• Target — ベース URL、プロトコル（rest | soap）、タイムアウト、デフォルトヘッダーです。
• AuthSpec — type（none、api_key、basic、bearer、oauth2_client_credentials）と、そのタイプに応じた形式の config 辞書です。OAuth2 トークンは自動的に取得され、キャッシュされます。
• RequestFormat ／ ResponseFormat — コンテンツタイプ（json、xml、soap）に加え、コードを書かずにペイロードを変換する宣言的な field_map（{"target.path": "$.source.jsonpath"}）、または完全な制御が可能な Jinja2 の body_template（SOAP エンベロープでは必須）を指定します。
• InvokeSpec — 上記 3 つをまとめた、「1 つのサービスへの接続方法」を表す単位です。名前付きの Connector として保存するか、呼び出しごとにインラインで渡します。

完全なスキーマについては src/mcp_api_connect/core/models.py を、各認証 type が必要とする config の形式については docs/auth-reference.md をご覧ください。

ドキュメント

• docs/mcp-integration.md — MCP クライアントの完全なセットアップ（Claude Desktop、Claude Code、Cursor）、永続化、セキュリティ、ツールのリファレンス、実例、トラブルシューティング
• docs/auth-reference.md — すべての認証タイプの config フィールド
• CONTRIBUTING.md — 開発環境のセットアップ、テストの実行、PR に関する要件

拡張

• 新しい認証タイプ：AuthStrategy を実装し、engine.register_auth_strategy(...) で登録します。
• 新しいプロトコル（例：GraphQL）：ProtocolAdapter を実装し、engine.register_adapter(...) で登録します。
• 新しいコネクターのストレージバックエンド：ConnectorStore を実装します（InMemoryConnectorStore と SqliteConnectorStore が付属し、認証情報は Fernet を使用して保存時に暗号化されます）。

ロードマップ

• OAuth2 認可コードフロー、mTLS、AWS SigV4 認証方式
• WSDL 駆動の SOAP（任意の zeep ベースのアダプターを使用し、エンベロープを手書きする必要はありません）
• GraphQL アダプター
• Postgres をバックエンドとする ConnectorStore
• コネクターごとの再試行／バックオフおよびレート制限ポリシー
• パブリックデプロイ向けの SSRF 対策済みターゲット許可リスト

開発

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,storage,mcp]"
pytest

ライセンス

Apache License 2.0 — LICENSE と NOTICE をご覧ください。

コントリビューションには同じライセンスが適用されます（受け入れ側のライセンス＝提供側のライセンス）。詳細は CONTRIBUTING.md をご覧ください。

商標

mcp-api-connect™ は Balaji Venkatasubramaniyar の商標です。Apache 2.0 ライセンスは著作権および特許を対象としますが、商標権は付与しません。この名称は、このプロジェクトへの言及や互換性の表明には使用できますが、フォーク、製品、サービスの名称として使用したり、推奨を受けていると示唆したりすることはできません。ポリシーの全文は TRADEMARKS.md をご覧ください。