openapi-dynamic

目次

• 概要
• 主な特長
• 要件
• クイックスタート
• 設定
• クライアントのセットアップ
• CLI
• 認証
• 環境変数
• レスポンスの扱い方
• ファイルとバイナリデータ
• MCP ツール
• 開発
• ライセンス

概要

openapi-dynamic-mcp を使うと、MCP クライアントやシェルユーザーは、サービスごとにカスタムの接続コードを書くことなく OpenAPI API を利用できます。1 つ以上の OpenAPI 仕様を指定するだけで、一貫したインターフェースから API の一覧表示、エンドポイントの確認、認証、リクエストの送信ができます。

一般的なユーザーワークフローを想定して設計されています。

• 複数の API を 1 つの MCP サーバー経由で接続する
• ローカルの仕様ファイルまたはホストされた specUrl 定義を使用する
• OpenAPI 3.0、3.1、Swagger 2.0 を扱う
• API キー、ベアラー、ベーシック、OAuth2 認証に対応する
• 保存したトークンをセッション間で再利用する
• 大きなレスポンスから必要なフィールドだけを絞り込む
• リクエストを安全にプレビューしてから送信する

主な特長

• 仕様からすぐに使えるツールへ：YAML 設定から開始して、MCP または CLI からすぐにエンドポイントを参照したり、呼び出したりできます。
• API に合わせた認証：API キー、ベアラー／ベーシック認証、OAuth2 のクライアント認証情報、パスワード、デバイスコード、PKCE を使う認可コードに対応しています。
• サインインの繰り返しを回避：トークンを一度保存すれば、後から再利用できます。
• 対話型 OAuth をスムーズに処理：デバイスコード認証とブラウザーベースの認証では、エージェントがユーザーに提示できる手順が返されます。
• レスポンスに必要な情報だけを表示：JSONPath セレクターを使って、大きな出力を絞り込めます。
• 送信前に確認：ドライランを使って、ネットワーク I/O を行わずにリクエストの形式をプレビューできます。
• 必要に応じてファイルをアップロード：マルチパートフォームのアップロードと、生のバイナリボディに対応しています。
• レート制限に柔軟に対応：429 Too Many Requests に対する再試行を設定できます。

要件

• Node.js 20+

クイックスタート

MCP サーバーを直接実行します。

npx -y openapi-dynamic-mcp@latest --config ./config.yaml

最小限の設定：

version: 1
apis:
  - name: pet-api
    specPath: ./pet-api.yaml

リモートの仕様を指定することもできます。

version: 1
apis:
  - name: pet-api
    specUrl: https://api.example.com/openapi.json

設定

使用する各 API を apis の下に追加します。各エントリでは、ローカルの仕様ファイルまたはリモートの仕様 URL を指定できます。

version: 1

apis:
  - name: pet-api
    specPath: ./pet-api.yaml
    # specUrl: https://api.example.com/openapi.yaml
    baseUrl: https://api.example.com/v1
    timeoutMs: 30000
    headers:
      X-Client: openapi-dynamic-mcp
    retry429:
      maxRetries: 2
      baseDelayMs: 250
      maxDelayMs: 5000
      jitterRatio: 0.2
      respectRetryAfter: true
    oauth2Schemes:
      OAuthCC:
        tokenUrl: https://auth.example.com/oauth2/token
        scopes: [read:pets, write:pets]
        tokenEndpointAuthMethod: client_secret_basic
      UserAuth:
        authMethod: device_code
        deviceAuthorizationEndpoint: https://auth.example.com/oauth/device
        pkce: true

一般的なオプション：

• name：MCP および CLI コマンドに表示される API 名
• specPath または specUrl：OpenAPI 仕様の読み込み元
• baseUrl：仕様に記載されたサーバー URL を上書きする値
• headers：すべてのリクエストで送信するヘッダー
• timeoutMs：デフォルトのリクエストタイムアウト
• retry429：レート制限された API に対する再試行の動作
• oauth2Schemes：仕様で OAuth セキュリティが定義されている場合に、スキームごとに設定する OAuth 設定

スキームごとの OAuth2 設定

API に 1 つ以上の OAuth2 セキュリティスキームが定義されていて、特定のスキームに対してトークン URL、スコープ、または対話型認証の設定を行いたい場合は、oauth2Schemes を使用します。

スキーム名は OpenAPI 仕様内の名前と一致させる必要があります。一般的なオプションは次のとおりです。

• tokenUrl
• scopes
• tokenEndpointAuthMethod
• authMethod
• deviceAuthorizationEndpoint
• pkce

認証情報の設定だけが必要な場合は、環境変数で十分なことが多いです。プロジェクトにチェックインして再利用できる設定が必要な場合は、oauth2Schemes を使用してください。

クライアントのセットアップ

Claude Desktop / Claude Code

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-dynamic-mcp@latest",
        "--config",
        "/absolute/path/to/config.yaml"
      ],
      "env": {
        "PET_API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-dynamic-mcp@latest",
        "--config",
        "/absolute/path/to/config.yaml"
      ]
    }
  }
}

CLI

サーバーモードは、ルートコマンドまたは明示的な serve サブコマンドのいずれかで利用できます。

openapi-dynamic-mcp --config ./config.yaml
openapi-dynamic-mcp serve --config ./config.yaml

MCP クライアント以外から同じ API にアクセスしてスクリプトを作成したり、デバッグしたり、認証を設定したりする場合は、CLI を使用してください。

ツールコマンド

すべての MCP ツールは、1 つの JSON オブジェクトを受け取り、JSON 出力を返す CLI サブコマンドとしても利用できます。

openapi-dynamic-mcp list_apis --config ./config.yaml --input '{}'
openapi-dynamic-mcp list_api_endpoints --config ./config.yaml --input '{"apiName":"pet-api"}'
openapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets"}'
openapi-dynamic-mcp get_api_schema --config ./config.yaml --input '{"apiName":"pet-api","pointer":"/info"}'
openapi-dynamic-mcp make_endpoint_request --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets","dryRun":true}'

共通フラグ：

• --input <json>：コマンド引数を含む JSON オブジェクト
• --fields <jsonpath>：成功した出力をフィルタリングするための、繰り返し指定可能なセレクター
• --describe：コマンドのスキーマとヘルプメタデータを出力します
• --auth-file <path>：認証ストアのパスを上書きします

認証コマンド

auth を使用すると、設定済みのセキュリティスキームを事前認証し、そのトークンを保存して、後続の MCP または CLI 呼び出しで利用できます。

openapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme OAuthCC
openapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme ApiKeyAuth --token secret

API キー認証とベアラー認証では、--token でシークレットを直接指定できます。OAuth2 の場合、コマンドは設定済みの認証情報を使用してフローを完了し、結果を保存して後で利用できるようにします。

認証

対応している認証タイプ：

• API キー
• HTTP ベアラー
• HTTP ベーシック
• OAuth2 クライアントクレデンシャル
• OAuth2 パスワードグラント（ROPC）
• OAuth2 デバイスコード
• OAuth2 PKCE による認可コード

一般的な認証フロー：

1. 環境変数または設定を通じて認証情報を指定します
2. スキームでトークンの保存が必要な場合は、auth を一度実行します
3. トークンの期限が切れるか変更されるまで、MCP または CLI からそのトークンを再利用します

認証ストア

デフォルトでは、トークンは設定ファイルと同じ場所にある次のファイルに保存されます。

.openapi-dynamic-mcp-auth.json

次のいずれかを使用して、保存先を上書きできます。

• --auth-file
• OPENAPI_DYNAMIC_MCP_AUTH_FILE

これにより、API の反復的な利用が格段にスムーズになります。特に、頻繁な再接続が必要な MCP クライアントで役立ちます。

対話型 OAuth2 フロー

リクエストでユーザーの操作が必要な場合、ツールは MCP エージェントがユーザーに伝えられる構造化されたガイダンスを返します。一般的なデバイスコードの出力例は次のとおりです。

{
  "status": "authorization_required",
  "method": "device_code",
  "message": "User authorization required. Ask the user to visit the URL and enter the code.",
  "verificationUri": "https://auth.example.com/device",
  "userCode": "ABCD-1234",
  "instruction": "After the user confirms, call this endpoint again."
}

この仕組みにより、認証ステップが行き止まりのエラーではなく、ユーザーのワークフローの通常の一部となるため、MCP エージェントにとって特に便利です。

環境変数

環境変数は、シークレット、ベース URL の上書き、CI の設定に便利です。

名前は、API 名とスキーム名を正規化して生成されます。

• 大文字にする
• 英数字以外の文字を _ に置き換える
• 連続する _ を 1 つにまとめる
• 先頭と末尾の _ を削除する

例：

• pet-api -> PET_API
• OAuth2 -> OAUTH2

API レベルの変数

• <API>_BASE_URL
• <API>_HEADERS：JSON オブジェクト文字列
• OPENAPI_DYNAMIC_MCP_AUTH_FILE

API キー

• <API>_<SCHEME>_API_KEY

HTTP 認証

• <API>_<SCHEME>_TOKEN
• <API>_<SCHEME>_USERNAME
• <API>_<SCHEME>_PASSWORD

OAuth2

• <API>_<SCHEME>_ACCESS_TOKEN
• <API>_<SCHEME>_CLIENT_ID
• <API>_<SCHEME>_CLIENT_SECRET
• <API>_<SCHEME>_TOKEN_URL
• <API>_<SCHEME>_SCOPES：スペース区切りのリスト
• <API>_<SCHEME>_TOKEN_AUTH_METHOD：client_secret_basic または client_secret_post
• <API>_<SCHEME>_USERNAME
• <API>_<SCHEME>_PASSWORD
• <API>_<SCHEME>_AUTH_METHOD：device_code または authorization_code
• <API>_<SCHEME>_DEVICE_AUTHORIZATION_ENDPOINT
• <API>_<SCHEME>_REDIRECT_PORT
• <API>_<SCHEME>_PKCE：true または false

便利な動作：

• _ACCESS_TOKEN は OAuth グラントフローをすべて省略します。
• 両方の方式が利用可能な場合、_AUTH_METHOD は device_code または authorization_code を指定します。
• _USERNAME と _PASSWORD は、セキュリティスキームに応じて HTTP ベーシック認証と OAuth パスワードグラントの両方に使用されます。

レスポンスの操作

JSONPath によるフィルタリング

CLI の --fields と MCP の fields: string[] を使うと、成功したレスポンスから必要な部分だけを残せます。仕様やペイロードが大きすぎて簡単に確認できない場合に便利です。

例：

openapi-dynamic-mcp list_apis --config ./config.yaml --fields '$.apis[*].name'
openapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets"}' --fields '$.responses'

セレクターは、引用符付きメンバーのエスケープ、配列インデックス、ワイルドカードに対応しています。

大規模スキーマに関する警告

get_api_schema は、レスポンスが非常に大きい場合に _sizeWarning というアドバイザリーフィールドを追加し、JSON Pointer の範囲を絞るよう促します。

ドライラン

make_endpoint_request は dryRun: true に対応しているため、実際のリクエストを送信する前に URL、ヘッダー、認証情報、シリアライズされた本文を確認できます。

ファイルとバイナリデータ

make_endpoint_request は multipart/form-data と生のバイナリのアップロードの両方に対応しています。

各ファイルエントリーには、コンテンツソースとして base64、text、filePath のいずれか1つを指定する必要があります。

{
  "name": "avatar.png",
  "contentType": "image/png",
  "filePath": "/absolute/path/to/avatar.png"
}

マルチパートの例：

{
  "apiName": "pet-api",
  "endpointId": "uploadProfile",
  "contentType": "multipart/form-data",
  "body": {
    "description": "A photo of Fido"
  },
  "files": {
    "profileImage": {
      "name": "fido.jpg",
      "contentType": "image/jpeg",
      "filePath": "/Users/local/images/fido.jpg"
    }
  }
}

生のバイナリの例：

{
  "apiName": "pet-api",
  "endpointId": "uploadRaw",
  "contentType": "application/octet-stream",
  "files": {
    "body": {
      "filePath": "/Users/local/data.bin"
    }
  }
}

MCP ツール

以下の5つのツールで、主なユーザーワークフローに対応します。

ツール	目的
list_apis	設定済みの API を一覧表示します
list_api_endpoints	1つの API のエンドポイントを検索またはページネーションします
get_api_endpoint	エンドポイントのメタデータ、パラメーター、レスポンス、セキュリティを確認します
get_api_schema	仕様からスキーマオブジェクトまたは JSON Pointer の対象を返します
make_endpoint_request	エンドポイントリクエストをプレビューまたは実行します

開発

npm install
npm run build
npm test

便利なコマンド：

npm run lint
npm run format
npm run test:watch

ライセンス

MIT