OpenAPI Services

mcp-openapix

あらゆる OpenAPI サービスを、4 つの汎用ツールを通じて利用できるようにするMCP サーバーです。

エージェントは各デプロイメントの OpenAPI ドキュメントから操作を見つけて呼び出します。サーバーは URL を解決し、ベアラートークンを取得して、リクエストを構築します。操作の検出には list_platforms、list_endpoints、describe_endpoint を使用し、実行には汎用プロキシ call_endpoint を使用します。

example / us / items / prod
  │     │     │      └── env ......... which deployment URL a call reaches
  │     │     └───────── service ..... one backend, one OpenAPI spec
  │     └─────────────── region ...... a geographic deployment
  └───────────────────── platform .... the product or API family

必要条件

• Python 3.13+ と uv
• 認証情報を持つデプロイメントを記述した config.json

クイックスタート

設定を準備して（設定を参照）、サーバーを起動します。

# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector@latest uvx mcp-openapix

# Or run from source
npx -y @modelcontextprotocol/inspector@latest uv run mcp-openapix

設定

config.json は ~/.config/mcp-openapix/config.json（Windows では %USERPROFILE%\.config\…）に配置する必要があります。config.example.json は完全なテンプレートです。

{
  "headers": { "accept": "application/json" },
  "defaults": { "platform": "example", "region": "us", "service": "items", "env": "prod" },
  "platforms": {
    "example": {
      "regions": {
        "us": {
          "services": {
            "token_helper": "us",
            "items": {
              "desc": "Catalogue and inventory API",
              "spec_path": "/swagger/v1/swagger.json",
              "canonical_env": "prod",
              "envs": {
                "prod": { "url": "https://api.example.com/items" },
                "dev":  { "url": "https://api-dev.example.com/items" }
              }
            }
          }
        }
      }
    }
  },
  "token_helpers": {
    "us": {
      "command": "token-helper",
      "args": ["issue"]
    }
  }
}

platforms

platform → region → services → service → env という階層です。各サービスでは次の項目を宣言します。

services オブジェクトには、そのリージョン内のすべてのサービスに適用されるデフォルトの token_helper も含められます。サービスまたは環境で上書きできます。

token_helpers

MCP サーバーのエントリーと同じ形式で指定する、名前付きトークンヘルパーです。

設定に記述するのはコマンドだけなので、config.json にシークレットは含まれません。ヘルパーの完全な呼び出し方法と出力仕様については、docs/token-protocol.md を参照してください。

呼び出しで使用するヘルパーは、より具体的な階層から順に解決されます。

env.token_helper → service.token_helper → services.token_helper
→ region.token_helper → platform.token_helper → defaults.token_helper

どの階層にもヘルパーが宣言されていない場合、デプロイメントは認証なしで使用されます。公開デプロイメントでは token_helper を省略してください。

headers

テナント、製品、ロケールのヘッダーを必要とする API 向けに、すべての API 呼び出しに追加される固定ヘッダーです。

"headers": { "accept": "application/json", "x-product": "example" }

defaults

すべてのツール引数を任意にします。省略された引数については、呼び出し時に defaults.platform、.region、.service、.env、.username、.token_helper の値が使用されます。

トップレベルのオプション

設定の分割

あるプラットフォームを編集中に誤ってカンマを入れると、プラットフォームごとの検証より先に解析エラーが発生し、すべてのプラットフォームが停止します。そのため、設定を nginx の conf.d のように、config.d/ 内のドロップインファイルに分割できます。推奨するレイアウトでは、サーバー全体の設定を config.json に置き、各プラットフォームにはプラットフォーム名を付けた独自のファイルを用意します。

~/.config/mcp-openapix/
├── config.json      # defaults, headers, token_helpers, top-level options
└── config.d/
    ├── acme.json    # {"platforms": {"acme": …}}
    └── public.json  # {"platforms": {"public": …}}

この場合、誤記の影響は1つのプラットフォームに限られ、プラットフォームを1つのファイルとして引き継いだり、削除したりできます。トークンヘルパーは通常プラットフォーム間で共有されるため、config.json に置きます。1つのプラットフォームだけが使うヘルパーは、そのプラットフォームのファイルと一緒に置いてもかまいません。

このレイアウトは慣例であり、規則ではありません。

• config.json が最初に読み込まれ、その後 config.d/ 直下のすべての *.json がソート順に読み込まれます。サブディレクトリ、.bak、エディターのスワップファイルは無視されます。config.d/ がなければ、動作に変更はありません。
• ドロップインファイルには、config.json で宣言できる任意の項目を記述できます。また、config.json はほぼ空でもかまいません。
• ファイルは、その順序で1つの設定に貼り合わせたかのようにマージされます。オブジェクトはキーごとにマージされ、後のスカラー値やリストは前の値を置き換えます。そのため、後のファイルから単一の envs.prod.url や defaults のフィールドを上書きできます。

解析に失敗したファイルの影響は、そのファイルが宣言する内容だけに限られます。それ以外は引き続き動作します。どのファイルにあるかを問わず、不正なプラットフォームによって他のプラットフォームの読み込みが止まることはありません。また、そのプラットフォームが指定するトークンヘルパーが見つからない場合も同様です。ヘルパーが別のファイルで宣言されている可能性があるため、エラーにはスキップされたファイルが記載されます。list_platforms では、読み込みに失敗したプラットフォームはリージョンなしで表示され、ローダーの error が示されます。スキップされたファイルは {"file", "error"} として表示されます。読み込みに失敗したプラットフォームを呼び出すと、同じメッセージが返されます。読み込みに失敗したプラットフォームを参照するデフォルト値は無視されます。platforms の外にある無効な設定は、引き続きサーバーを停止させ、その設定を指定したファイル名がメッセージに示されます。

修正を反映するには再起動が必要です。サーバーを起動せずに、まず設定を確認してください。後のファイルによって上書きされた値もすべて表示されます。

uvx mcp-openapix --check-config

ツール

操作 ID

多くの OpenAPI ドキュメントでは operationId が省略されているため、サーバーは "<METHOD> <path>" の形式で操作 ID を生成します。

POST /api/items
└─┬─┘ └───┬───┘
method  path as the spec declares it

仕様書で operationId が宣言されている場合は、その値が優先されます。

仕様書

仕様書は同梱されていません。各デプロイメントのドキュメントは必要に応じて認証なしの GET で取得され、~/.cache/mcp-openapix/{platform}/{region}/{service}.json にキャッシュされます。

ドキュメントは、インストール前に少なくとも1つの操作を宣言している必要があります。そのため、エラー本文とともに 200 を返すデプロイメントによって、何も提供しないスナップショットが正常なスナップショットを置き換えることはありません。

キャッシュされた仕様書はバックグラウンドで更新されます。起動時に1回、その後は spec_refresh.interval 日ごとに更新されます。停止するには auto を false に設定してください。手動更新は引き続き利用できます。

uvx mcp-openapix --refresh

MCP リソース

どちらも呼び出しから response_cache_ttl 秒後に期限切れになります。curl コマンドには、有効期間の短いトークンが埋め込まれることがあります。

保存時のトークン

トークンはメモリーにキャッシュされ、有効期限のメタデータがある場合は、トークンヘルパーの宣言とユーザー名をキーとして ~/.cache/mcp-openapix/tokens/ にも保存されます（モード 0600）。これにより、クライアントセッション間でログインを共有でき、セッションごとにヘルパーを起動する必要がなくなります。401 が返されると、キャッシュされたトークンは無効化され、次の呼び出しで新しいトークンが取得されます。すべてのトークンを消去するには、次のようにします。

uvx mcp-openapix --logout

MCP ホストの例

{
  "mcpServers": {
    "openapi": { "command": "uvx", "args": ["mcp-openapix"] }
  }
}

[mcp_servers.openapi]
command = "uvx"
args = ["mcp-openapix"]

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

4 つすべてに必ず合格する必要があります。AGENTS.md を参照してください。テストでは、HTTP のモックに respx を使用し、トークンヘルパーには実際のサブプロセスを使用するため、 実際の API へのアクセスは不要です。

ライセンス

MIT。