OpenAPI to MCP Generator (openapi-mcp-generator)

OpenAPI から MCP へのジェネレーター（openapi-mcp-generator）

openapi-mcp-generator は、OpenAPI 3.x 仕様を、stdio、SSE、Streamable HTTP、または Cloudflare Workers に対応した、すぐに実行できる Model Context Protocol（MCP） サーバーに変換する、MIT ライセンスの無料 CLI およびライブラリです。 生成された TypeScript コードはご自身で管理でき、API にリクエストが届く前に、ツールの入力が JSON Schema に照らして検証されます。

ドキュメント · クイックスタート · ブラウザプレイグラウンド · 変更履歴

npx openapi-mcp-generator --input ./openapi.json --output ./my-mcp

---

✨ 機能

• 🔧 OpenAPI 3.x のサポート：任意の OpenAPI 3.0 または 3.1 仕様を、MCP 互換のサーバーに変換します（Swagger 2.0 は先に変換してください）。
• 🔁 プロキシ動作：リクエストの構造とセキュリティを検証しながら、元の REST API への呼び出しをプロキシします。
• 🔐 認証のサポート：API キー、Bearer トークン、Basic 認証、OAuth2 に対応しています。環境変数を介して設定でき、必要な認証情報がない場合、呼び出しは安全側に失敗します。
• 🧪 JSON Schema 検証：引数は各ツールの JSON Schema 2020-12 入力スキーマに照らして検証されます（コード生成や eval は使用しません）。
• 🏷️ アノテーションと構造化出力：ツールにはタイトルと、読み取り専用／破壊的／冪等のヒントが付与されます。また、JSON オブジェクトのレスポンスは structuredContent として返されます（宣言された outputSchema を任意で指定できます）。
• ⚙️ 型付きサーバー：保守しやすい、完全に型付けされた TypeScript コードを出力します。
• 🔌 複数のトランスポート：stdio、Hono を介した SSE、StreamableHTTP、またはデプロイ可能な Cloudflare Worker を使って通信できます。
• 🧰 プロジェクトのひな形：tsconfig.json、package.json、エントリーポイントを含む、完全な Node.js プロジェクトを生成します。
• 🧪 組み込み HTML テストクライアント：ブラウザ上で API のやり取りを視覚的にテストできます（Web ベースのトランスポート向け）。

---

🚀 インストール

npm install -g openapi-mcp-generator

yarn global add openapi-mcp-generator または pnpm add -g openapi-mcp-generator も使用できます。

---

⬆️ 5.0 へのアップグレード

5.0 では MCP TypeScript SDK v2 を使用してサーバーを生成し、2025 年代のクライアントとともに MCP 2026-07-28 をサポートします。生成されるプロジェクトが変更されるため、計画的にアップグレードしてください。

1. 生成したプロジェクトをコミットしてから、同じフラグで再生成します：npx openapi-mcp-generator@5 -i ./openapi.json -o ./my-mcp --force。--force は編集内容を含む生成ファイルを上書きします。
2. ジェネレーターの実行には Node.js 22.19 以降を使用し（生成されるプロジェクトには Node.js 22 以降が必要です）、その後 npm install を実行します。@modelcontextprotocol/sdk は @modelcontextprotocol/server（^2.4.0）に置き換えられ、zod、json-schema-to-zod、dotenv、uuid は @cfworker/json-schema に置き換えられます。
3. カスタマイズしたコードを更新し、@modelcontextprotocol/server からインポートするようにします（stdio ヘルパーは @modelcontextprotocol/server/stdio からインポートします）。
4. Streamable HTTP サーバーと Worker サーバーはステートレスです。mcp-session-id はなく、/mcp への GET と DELETE は 405 を返します。POST によるツール呼び出しには影響しません。
5. 上流の認証情報が不足している場合、設定が必要な変数名を示すエラーが発生し、接続は拒否されるようになりました。MCP_ALLOW_MISSING_CREDENTIALS=true を設定すると、以前の動作に戻ります。
6. 不明なツール名は JSON-RPC の -32602 エラーになります。整数は整数のまま保持され、readOnly プロパティはリクエスト入力から除外され、スキーマのデフォルト値は注入されなくなりました。
7. Swagger 2.0 の仕様は受け付けられません。npx swagger2openapi swagger.json -o openapi.json で変換してください。
8. 認証情報の変数、Worker のシークレット名、--inbound-auth、--header-passthrough、MCP_ALLOWED_ORIGINS に変更はありません。

まだ準備ができていませんか？npx openapi-mcp-generator@4 で 4.x を使い続けてください。詳細：CHANGELOG.md。

---

🛠 使い方

# Generate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

# Generate an MCP web server with SSE
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

# Generate an MCP StreamableHTTP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000

# Generate a deployable Cloudflare Worker MCP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=cloudflare-worker

examples/ フォルダーには、5.0 で生成された Swagger Petstore があり、stdio（petstore-mcp）、web（pet-store-sse）、StreamableHTTP（pet-store-streamable-http）に対応しています。

CLI オプション

オプション	エイリアス	説明	デフォルト
--input	-i	OpenAPI 仕様（YAML または JSON）のパスまたは URL	必須
--output	-o	生成された MCP プロジェクトの出力先ディレクトリ	必須
--server-name	-n	MCP サーバーの名前（package.json:name）	OpenAPI のタイトルまたは mcp-api-server
--server-version	-v	MCP サーバーのバージョン（package.json:version）	OpenAPI のバージョンまたは 1.0.0
--base-url	-b	API リクエストのベース URL。OpenAPI の servers がない場合、または曖昧な場合に必須です。	可能な場合は自動検出
--transport	-t	トランスポートモード：「stdio」（デフォルト）、「web」、「streamable-http」、または「cloudflare-worker」	"stdio"
--port	-p	Web ベースのトランスポート用ポート	3000
--default-include		x-mcp フィルタリングのデフォルト動作です。true または false（大文字と小文字を区別しない）を指定します。true = デフォルトで含める、false = デフォルトで除外する。	true
--allow-external-refs		仕様内の外部 http(s) $ref 参照の解決を許可します。解析中の SSRF を防ぐため、デフォルトでは無効です。	false
--max-tool-name-length		生成するツール名の最大長（Claude Desktop の上限は 64 文字です）。長い名前はハッシュサフィックスを付けて切り詰められます。	64
--header-passthrough		上流 API に転送する受信ヘッダー名をカンマ区切りで指定します（web、streamable-http、cloudflare-worker）。ユーザーごとの API キーを有効にします。	(なし)
--inbound-auth		HTTP トランスポートの受信認証：「none」または「bearer」です。「bearer」の場合、クライアントは Authorization: Bearer <token>（MCP_AUTH_TOKEN）を送信する必要があります。	none
--insecure	-k	生成されたサーバーで安全でない HTTPS 接続を許可します（TLS 証明書の検証をスキップします）。	false
--generate-lib		ライブラリ形式の出力を生成します。自動的に実行する代わりに main() をエクスポートし、シグナル処理とクリーンアップの配線を省略します。	false
--custom-auth		編集可能な src/auth.ts フック（applyCustomAuth）を生成します。これは組み込み認証の前に呼び出され、true を返すと組み込み認証をスキップします。	false
--oauth-creds-in-body		OAuth2 クライアント認証情報を Basic Authorization ヘッダーの代わりにトークンリクエストの本文で送信します。	false
--include-tags		カンマ区切りのタグです。これらのいずれかを持つオペレーションのみを生成します（大文字と小文字を区別しません）。	(すべて)
--exclude-tags		カンマ区切りのタグです。いずれかを持つオペレーションをスキップします。除外は包含より優先されます。	(なし)
--include-operations		生成する operationId またはツール名をカンマ区切りで指定します。--include-tags と組み合わせると、いずれかに該当するものが対象になります。	(すべて)
--exclude-operations		スキップする operationId またはツール名をカンマ区切りで指定します。除外は包含より優先されます。	(なし)
--output-schema		各ツールの outputSchema を 2xx の JSON レスポンススキーマ（オブジェクトのみ）から宣言し、一致しないレスポンスを拒否します。	false
--force		確認せずに出力ディレクトリ内の既存ファイルを上書きします	false

実行時の API ベース URL の設定： 生成されたサーバーは環境変数（.env）から API_BASE_URL を読み取り、OpenAPI の servers リストから組み込まれた値を 上書きします。ポートは、まず --port、次に PORT 環境変数、最後に 3000 の順で 決定されます。

操作単位およびパス単位のサーバー： 操作の servers[0] がパス項目のサーバーより優先され、 パス項目のサーバーはルートサーバーより優先されます。サーバー変数にはデフォルト値が設定されます。絶対 URL の操作サーバーまたはパスサーバーは、API_BASE_URL が設定されていても使用されます。相対 URL の場合は、 有効なベース URL を基準に解決されます（"v2" はセグメントを追加し、"/v2" はパスを置き換えます）。

📦 プログラマティック API

このパッケージは CLI が使用するパーサーもエクスポートするため、独自の Node.js コード内で OpenAPI ドキュメントを MCP ツール 定義に変換できます。

import { getToolsFromOpenApi } from 'openapi-mcp-generator';

// From a local file or a URL
const tools = await getToolsFromOpenApi('./petstore.json', { dereference: true });

// With options
const readOnlyPetTools = await getToolsFromOpenApi(
  'https://petstore3.swagger.io/api/v3/openapi.json',
  {
    baseUrl: 'https://petstore3.swagger.io/api/v3',
    dereference: true,
    includeTags: ['pet'],
    excludeOperations: ['deletePet'],
    filterFn: (tool) => tool.annotations?.readOnlyHint === true,
  }
);

for (const tool of readOnlyPetTools) {
  console.log(`${tool.name}: ${tool.method.toUpperCase()} ${tool.pathTemplate}`);
}

getToolsFromOpenApi(spec, options?)

spec はファイルパス、http(s) URL、または解析済みの OpenAPIV3.Document です。この関数は Promise<McpToolDefinition[]> を返します。Swagger 2.0 ドキュメントは拒否されます。まず変換してください （npx swagger2openapi swagger.json -o openapi.json）。

オプション	説明	デフォルト
baseUrl	仕様の servers にあるベース URL を上書きします
dereference	ツールを抽出する前に $refs を解決します。指定しない場合、参照先のスキーマは未解決のままになり、それぞれについて警告が記録されます	false
includeTags / excludeTags	これらのタグを持つ操作のみを残す、または除外します（大文字と小文字は区別されません）
includeOperations / excludeOperations	これらの操作のみを残す、または除外します（operationId またはツール名）。CLI フラグと同じルールが適用されます。include は併用され、exclude が優先されます
excludeOperationIds	これらの operationId を除外します（旧オプション。上記のフィルター適用後に適用されます）
filterFn	カスタム述語 (tool) => boolean。最後に適用されます
defaultInclude	x-mcp 拡張がない操作を含めるかどうか	true
allowExternalRefs	外部 http(s) $refs を許可します。SSRF に利用されないよう、デフォルトでは無効です	false
maxToolNameLength	生成されるツール名の最大長（Claude Desktop では 64 文字まで）	64

フィルターは x-mcp によるフィルタリング後に適用されます。ドキュメントを自分で解析するには、その結果を渡してください。

import SwaggerParser from '@apidevtools/swagger-parser';
import type { OpenAPIV3 } from 'openapi-types';
import { getToolsFromOpenApi } from 'openapi-mcp-generator';

const api = (await SwaggerParser.dereference('./openapi.yaml')) as OpenAPIV3.Document;
const tools = await getToolsFromOpenApi(api);

ツール定義

interface McpToolDefinition {
  name: string; // unique tool name
  title?: string; // x-mcp-title, else the operation summary
  description: string;
  inputSchema: JSONSchema7 | boolean; // JSON Schema 2020-12 for the tool arguments
  method: string; // get, post, ...
  pathTemplate: string; // e.g. /pet/{petId}
  parameters: OpenAPIV3.ParameterObject[];
  executionParameters: { name: string; in: string }[];
  requestBodyContentType?: string;
  serverUrl?: string; // operation or path-item server, variables resolved
  baseUrl?: string; // set by getToolsFromOpenApi: the baseUrl option or root server, else ''
  securityRequirements: OpenAPIV3.SecurityRequirementObject[];
  operationId: string;
  tags?: string[];
  deprecated?: boolean;
  annotations?: McpToolAnnotations; // readOnlyHint, destructiveHint, idempotentHint, openWorldHint
  outputSchema?: JSONSchema7; // lowest 2xx application/json response, when it is an object
}

inputSchema は integer 型を保持し、example を examples に変換し、readOnly プロパティを除外します。アノテーションは HTTP メソッドから取得されます（GET と HEAD は読み取り専用、DELETE は 破壊的、PUT と DELETE は冪等）。操作ごとに x-mcp-annotations で上書きできます。getToolsFromOpenApi が返す各ツールには baseUrl が含まれます。これは baseUrl オプション、仕様のルートサーバー、または空文字列のいずれかです。操作またはパス項目のサーバーは serverUrl に格納され、API 呼び出し時に優先されます。

その他のフィルター：

const spec = './petstore.json';

// Only GET operations
await getToolsFromOpenApi(spec, { dereference: true, filterFn: (tool) => tool.method === 'get' });

// Only operations that require authentication
await getToolsFromOpenApi(spec, {
  dereference: true,
  filterFn: (tool) => tool.securityRequirements.length > 0,
});

// Read-only user endpoints, without two specific operations
await getToolsFromOpenApi(spec, {
  dereference: true,
  excludeOperationIds: ['deleteUser', 'updateUser'],
  filterFn: (tool) =>
    tool.pathTemplate.startsWith('/user') && tool.annotations?.readOnlyHint === true,
});

---

🧱 プロジェクト構成

生成されるプロジェクトには、以下が含まれます。

<output_directory>/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts
│   └── [transport-specific-files]
└── public/          # web and streamable-http: the browser playground
    ├── index.html, playground.js, playground.css, mcp-client.js
    └── playground.config.json

主な依存関係：

• @modelcontextprotocol/server - MCP プロトコルの実装（SDK v2）
• @cfworker/json-schema - ツールの引数（および --output-schema を指定した場合は出力）の JSON Schema 2020-12 検証
• axios - API リクエスト用の HTTP クライアント
• トランスポート固有の依存関係（hono、@hono/node-server）

.env は Node 組み込みの process.loadEnvFile() で読み込まれるため、dotenv への依存関係はありません。

---

📡 トランスポートモード

生成されるサーバーは MCP 2026-07-28（ステートレスなリクエスト、server/discover）に対応し、MCP TypeScript SDK v2 を使用して、initialize で接続を開始する 2025 年当時のクライアントにも引き続き対応します。仕様で HTTP+SSE は非推奨となっているため、web（SSE）トランスポートは 2025 年当時のプロトコルのままです。新規デプロイでは streamable-http を推奨します。

Stdio（デフォルト）

標準入力／出力を介して MCP クライアントと通信します。ローカル開発や LLM ツールとの連携に最適です。

SSE を使用した Web サーバー

以下の機能を備えた、完全に機能する HTTP サーバーを起動します。

• 双方向メッセージングのための Server-Sent Events（SSE）
• クライアントからサーバーへの通信に使用する REST エンドポイント
• / のブラウザープレイグラウンド
• 複数接続への対応
• 軽量な Hono フレームワークを使用

StreamableHTTP

以下の機能を提供する MCP StreamableHTTP トランスポートを実装します。

• HTTP 経由のステートレスな JSON-RPC：リクエストごとに新しいサーバーを起動するため、あらゆるロードバランサーの背後でスケールできます
• MCP 2026-07-28 および 2025 年当時のクライアントに対応（2025 年当時のクライアントはセッションなしで動作し、GET と DELETE には 405 を返します）
• 適切な HTTP レスポンスステータスコード
• 組み込みのエラーハンドリング
• MCP StreamableHTTPClientTransport との互換性
• / のブラウザープレイグラウンド
• 軽量な Hono フレームワークを使用

Cloudflare Worker

@modelcontextprotocol/server の createMcpHandler を使用し、Streamable HTTP を /mcp で提供する、完全なデプロイ可能な Cloudflare Workers プロジェクトを生成します（追加のフレームワーク依存関係はありません）。コマンド 1 つで、ご自身の Cloudflare アカウントにデプロイできます。

openapi-mcp-generator --input ./openapi.json --output ./my-mcp-worker --transport cloudflare-worker
cd my-mcp-worker
npm install
npx wrangler secret put API_KEY   # set upstream API secrets (see .dev.vars.example)
npx wrangler deploy               # Wrangler logs into YOUR Cloudflare account and deploys

主な特長：

• ステートレスで、無料の Workers ティアで動作します（Durable Objects や KV は不要）。リクエストごとに新しい MCP サーバーが作成されます。
• 最小限の依存関係：@modelcontextprotocol/server と @cfworker/json-schema のみで、追加のエージェントフレームワークは不要です。
• API_BASE_URL などの非シークレット設定は wrangler.jsonc の vars に保存します。シークレットは wrangler secret put で設定し、env バインディングから読み込みます。シークレットがコミットされることはありません。
• Workers ネイティブのランタイム：グローバルの fetch（Node の https は不使用）を使用し、引数は @cfworker/json-schema で JSON Schema に照らして検証します（コード生成や eval は行いません）。
• 認証方式を判別した認証に対応します。OpenAPI のセキュリティ要件のセマンティクスに従い、API キー（ヘッダー／クエリ／Cookie）、HTTP Basic／Bearer、OpenID Connect トークン、OAuth2 クライアントクレデンシャルは env のシークレットから取得されます（HTTP サーバーのセキュリティ保護を参照）。
• --inbound-auth bearer を指定すると、wrangler secret put MCP_AUTH_TOKEN で設定したトークンを使って /mcp を保護します。--header-passthrough は、クライアントからのユーザーごとの上流キーを転送します。
• --custom-auth、--port、--insecure、--generate-lib、--oauth-creds-in-body はこのターゲットでは適用されず、警告とともに無視されます。

ローカル開発の場合は、cp .dev.vars.example .dev.vars を実行し、使用するシークレットのコメントを解除して値を設定した後、npm run dev を実行します（http://localhost:8787/mcp で提供されます）。MCP Inspector を使うか、Claude Desktop から mcp-remote 経由で接続してください。

Transport Comparison

Feature	stdio	web (SSE)	streamable-http	cloudflare-worker
Protocol	JSON-RPC over stdio	JSON-RPC over SSE	JSON-RPC over HTTP	Streamable HTTP at /mcp
Connection	Persistent	Persistent	Request/response	Request/response
Bidirectional	Yes	Yes	Yes (stateless)	Yes
Multiple clients	No	Yes	Yes	Yes
Browser compatible	No	Yes	Yes	Yes
Firewall friendly	No	Yes	Yes	Yes
Load balancing	No	Limited	Yes	Yes (edge)
Status codes	No	Limited	Full HTTP codes	Full HTTP codes
Headers	No	Limited	Full HTTP headers	Full HTTP headers
Browser playground	No	Yes	Yes	Yes
Hosting	Local	Self-hosted	Self-hosted	Cloudflare (serverless)

---

🔐 認証用の環境変数

環境で認証情報を設定します。

認証タイプ	変数の形式
API キー	API_KEY_<SCHEME_NAME>
Bearer	BEARER_TOKEN_<SCHEME_NAME>
Basic 認証	BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>
OAuth2	OAUTH_TOKEN_<SCHEME_NAME>、または OAUTH_CLIENT_ID_<SCHEME_NAME>, OAUTH_CLIENT_SECRET_<SCHEME_NAME>, OAUTH_SCOPES_<SCHEME_NAME>
OpenID	OPENID_TOKEN_<SCHEME_NAME>

OAuth2 の場合、OAUTH_TOKEN_<SCHEME_NAME> はすでに取得済みのトークンで、すべてのフローで使用できます。 それ以外の場合、サーバーはトークンを取得します。スキームにクライアントクレデンシャルフローがある場合はクライアント ID とシークレットを使用し、パスワードフローのみの場合は OAUTH_USERNAME_<SCHEME_NAME> と OAUTH_PASSWORD_<SCHEME_NAME> を使用します（トークンエンドポイントで必要な場合は、クライアント ID と、機密クライアントの場合はシークレットも使用します）。

操作に複数のセキュリティ要件が記載されている場合、スキームがすべて設定されている最初の要件が使用されます。どの要件も満たせず（転送された --header-passthrough ヘッダーは設定済みとして扱われます）、操作が空の {} 要件による匿名アクセスを許可していない場合、ツールはフェイルクローズします。つまり、API を呼び出さず、設定すべき項目を示すエラーを返します。たとえば、Missing credentials for 'getPet': set API_KEY_PETSTORE_AUTH. のようなエラーです。代わりに MCP_ALLOW_MISSING_CREDENTIALS=true（Workers では Worker 変数）を設定すると、認証情報なしでリクエストを送信できます。OAuth2 トークンは、OAUTH_SCOPES_<SCHEME_NAME> で上書きされない限り、操作のスコープを指定して要求されます。Cloudflare Worker のターゲットでは、同じ認証情報を Wrangler のシークレット（<SCHEME_NAME>_API_KEY、<SCHEME_NAME>_TOKEN、<SCHEME_NAME>_USERNAME／_PASSWORD、<SCHEME_NAME>_CLIENT_ID／_CLIENT_SECRET）から読み込みます（生成された .dev.vars.example を参照）。OAuth2 の場合、<SCHEME_NAME>_TOKEN はすでに取得済みのトークンで、すべてのフローで使用できます。Worker がクライアント ID とシークレットからトークンを取得するのは、スキームでクライアントクレデンシャルフローが宣言されている場合のみです。

---

🧩 生成されるツール

• 入力スキーマ： OpenAPI スキーマからマッピングされた JSON Schema 2020-12 です。integer、format、 pattern、列挙型、allOf／anyOf／oneOf は保持され、nullable は null 型になり、example は examples になり、readOnly プロパティはリクエスト入力から除外されます。

• バリデーション： リクエストを送信する前に、引数がそのスキーマに照らして検証されます。問題がある場合は、 モデルが修正できるツールエラーとして返されます。たとえば、 Invalid arguments for tool 'getPet': /petId: Instance type "string" is invalid. Expected "integer". のようになります。引数は渡されたとおりに渡されます。スキーマのデフォルト値は挿入されません。

• エラー： 引数が無効な場合、認証情報がない場合、上流で障害が発生した場合はツールエラーになります （isError: true）。不明なツール名は、MCP 2026-07-28 仕様で定められているとおり、 JSON-RPC -32602 プロトコルエラーになります。

• タイトルと注釈： タイトルには、操作の x-mcp-title があればそれを使用し、なければその summary を 使用します。ヒントは HTTP メソッドに従います。GET／HEAD／OPTIONS は読み取り専用、POST は破壊的ではなく 冪等でもなく、PUT と DELETE は破壊的かつ冪等、PATCH は破壊的かつ冪等ではありません。すべて オープンワールドです。操作ごとに個別のヒントを上書きできます。

  paths:
    /pets/{id}:
      delete:
        x-mcp-title: Remove a pet
        x-mcp-annotations:
          destructiveHint: false # a soft delete
  

• 構造化出力： オブジェクトである JSON レスポンスは、structuredContent としても返されます。 --output-schema を指定すると、各ツールは最も低い 2xx application/json レスポンスのスキーマを outputSchema として宣言します（オブジェクトスキーマのみ。writeOnly プロパティは削除されます）。また、 すべてのレスポンスがそのスキーマに照らして検証されます。一致しないレスポンスは、未加工の本文も表示する ツールエラーになります。仕様が実際のレスポンスを正確に記述していない場合は、無効のままにしてください。

• サーバーの指示： 仕様の info.description（前後の空白を除去し、最大 2000 文字）が、 サーバーの指示としてクライアントに送信されます。

---

🔒 HTTP サーバーのセキュリティ保護

生成された web、streamable-http、cloudflare-worker サーバーは、ネットワークエンドポイントを公開します。 上流の認証情報も保持している場合、そのエンドポイントにアクセスできる人なら誰でも認証情報を使えるため、 ジェネレーターは保護なしでそのようなサーバーを生成すると警告します。

--inbound-auth bearer を使ってトークンを必須にする：

openapi-mcp-generator -i openapi.json -o my-mcp -t streamable-http --inbound-auth bearer
openssl rand -hex 32   # put the value in .env as MCP_AUTH_TOKEN (Workers: wrangler secret put MCP_AUTH_TOKEN)

• すべての MCP リクエストで Authorization: Bearer <token> を送信する必要があります。それ以外のリクエストは、 ツールが実行される前に 401 で拒否されます。/health は引き続き公開されます。
• トークンは実行時に読み込まれ、生成されたファイルには書き込まれません。また、一定時間で比較されます。 MCP_AUTH_TOKENS=new-token,old-token を使えば、ダウンタイムなしでローテーションできます。
• トークンが設定されていない場合、サーバーはフェイルクローズの動作となり、503 を返します。
• SSE セッションは、セッションを開始したトークンに紐付けられます。別のトークンでセッション ID を再使用すると、 404 が返されます。Streamable HTTP はステートレスで、リクエストごとにトークンを確認します。
• カスタムヘッダーに対応したクライアント（Claude Code、Cursor、VS Code、MCP Inspector、mcp-remote）は、 トークンを直接送信します。Claude.ai と ChatGPT のコネクターは OAuth または認証なしを使用するため、 OAuth 対応ゲートウェイの背後に配置してください。

--header-passthrough X-API-Key を使って、各ユーザーに自身の上流キーを使用してもらうことができます。 指定したヘッダーはリクエストごとに転送されるため、サーバーに共有シークレットを保存する必要はありません。 転送されるヘッダー内の認証情報がセキュリティスキームを満たす場合、AND 要件のその他のスキームは引き続き サーバー設定から適用されます。--inbound-auth bearer が有効な場合、Authorization ヘッダーは MCP トークンを 運ぶため、パススルーで転送できません。

ブラウザーのオリジン。 Node HTTP サーバーは、Origin がループバックアドレスでも MCP_ALLOWED_ORIGINS （カンマ区切り）に指定されたものでもないブラウザーリクエストを拒否します。これにより、ユーザーのマシン上で 実行されているサーバーに対する DNS リバインディング攻撃を防ぎます。Origin ヘッダーを送信しない MCP クライアントには 影響しません。

--inbound-auth は stdio には影響しません。stdio サーバーにはネットワークエンドポイントがなく、起動した プロセスだけが通信できます。

脆弱性を発見しましたか？SECURITY.md をご覧ください。

---

🔎 OpenAPI 拡張機能によるエンドポイントのフィルタリング

ベンダー拡張フラグ x-mcp を使って、MCP ツールとして公開するオペレーションを制御できます。この拡張機能はルート、パス、オペレーションの各レベルでサポートされています。明示的に除外されていない限り、エンドポイントはデフォルトで含まれます。

• 拡張機能：x-mcp: true | false
• デフォルト：true（デフォルトで含める）
• 優先順位：オペレーション > パス > ルート（未定義でない最初の値を使用）
• CLI オプション：--default-include false を指定すると、デフォルトで除外する設定に変更できます

例：

# Optional root-level default
x-mcp: true

paths:
  /pets:
    x-mcp: false # exclude all ops under /pets
    get:
      x-mcp: true # include this operation anyway

  /users/{id}:
    get:
      # no x-mcp -> included by default

これは標準の OpenAPI 拡張機能（x-… フィールド）を使用します。詳しくは OpenAPI Extensions guide をご覧ください。

注：x-mcp はブール値、または文字列 "true"／"false"（大文字と小文字を区別しません）である必要があります。それ以外の値は無視され、優先順位の高い設定またはデフォルトの動作が適用されます。

コマンドラインからのフィルタリング

大規模な API も、仕様を編集せずに厳選できます。

openapi-mcp-generator -i openapi.json -o my-mcp \
  --include-tags pets,store --exclude-operations deletePet

• --include-tags／--exclude-tags は、オペレーションのタグを大文字と小文字を区別せずに照合します。
• --include-operations／--exclude-operations は、operationId または生成されたツール名を照合します。
• フィルターは x-mcp と --default-include の適用後に適用されるため、除外されたオペレーションが再び含まれることはありません。包含リストは組み合わせて適用され（いずれかに一致すればオペレーションを保持）、除外は常に優先されます。
• プログラム API でも同じフィルターを指定できます：includeTags、excludeTags、includeOperations、excludeOperations。

---

▶️ 生成されたサーバーの実行

cd path/to/output/dir
npm install

# Run in stdio mode
npm start

# Run in web server mode
npm run start:web

# Run in StreamableHTTP mode
npm run start:http

🧪 ブラウザプレイグラウンド

web、streamable-http、cloudflare-worker 用に生成されたサーバーでは、/ にプレイグラウンドが表示されます（http://localhost:<port>/、または Worker の場合は npm run dev で http://localhost:8787/）。ツール一覧が表示され、各ツールの入力スキーマからフォームが作成されます。フォームからツールを実行し、すべての JSON-RPC メッセージを確認できます。また、curl としてコピーする機能や、Claude Code、Cursor、VS Code 向けの設定も用意されています。--inbound-auth bearer を指定してサーバーを生成した場合は、MCP_AUTH_TOKEN の値を貼り付けてください。この値はブラウザーのタブ内に保持されます。

• ページは厳格な Content-Security-Policy を適用したサーバー自身のオリジンから配信されるため、ローカルテストで CORS や MCP_ALLOWED_ORIGINS を変更する必要はありません。サーバーの出力は常にテキストとして描画されます。
• ページには Resources、Prompts（引数補完機能付き）、Logs、Raw JSON-RPC の各タブもあります。時間のかかるツール呼び出しでは［キャンセル］ボタン付きで進行状況が表示され、サーバーからのリクエスト（elicitation フォーム、サンプリング（返信は手動で入力）、roots）にも応答します。
• 同じオープンソースのページが mcp.pidata.tech/playground でホストされており、何もインストールせずに任意のリモート MCP サーバーへ接続できます。カスタムヘッダー、OAuth サインイン（検出、Client ID Metadata Documents または動的登録、PKCE）に対応し、ブラウザーからのリクエストをブロックするサーバー向けに、オプションのオープンソースリレーも利用できます。生成された Worker は CORS リクエストに応答するため、このページや他のブラウザークライアントから直接アクセスできます。Node サーバーの場合は、ページのオリジンを MCP_ALLOWED_ORIGINS に追加してください。
• たとえば本番環境でプレイグラウンドの配信を停止するには、MCP_PLAYGROUND=off（Node）を設定するか、MCP_PLAYGROUND 変数を "off"（Worker）に設定します。
• stdio サーバーには HTTP エンドポイントがありません。MCP Inspector でテストしてください。

---

⚠️ 要件

• ジェネレーターの実行には Node.js 22.19 以降が必要です。生成されたプロジェクトには Node.js 22 以降が必要です（Node 20 は 2026 年 4 月にサポート終了）

---

スターの推移

## 🤝 貢献

貢献を歓迎します！

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. npm run format.write を実行してコードをフォーマットします
4. 変更をコミットします：git commit -m "Add amazing feature"
5. プッシュして PR を作成します

📌 リポジトリ：github.com/harsha-iiiv/openapi-mcp-generator

---

📄 ライセンス

MIT License — 詳細は LICENSE をご覧ください。