generate-mcp-server

generate-mcp-server

Speakeasy を使用して、OpenAPI 仕様から Model Context Protocol（MCP）サーバーを生成します。MCP サーバーは、Claude などの AI アシスタントが直接呼び出せるツールとして API 操作を公開します。

使用するタイミング

• ユーザーが自分の API から MCP サーバーを作成したい場合
• ユーザーが Model Context Protocol との統合について尋ねた場合
• ユーザーが AI アシスタントに自分の API を操作させたい場合
• ユーザーが「MCP サーバーを生成」「MCP サーバーを作成」「speakeasy MCP」と言った場合
• ユーザーが「自分の API を Claude から利用できるようにするには？」と尋ねた場合
• ユーザーが「mcp-typescript」「AI アシスタントのツール」「Claude のツール」に言及した場合

入力

入力	必須	説明
OpenAPI 仕様	はい	OpenAPI 仕様へのパスまたは URL
パッケージ名	はい	MCP サーバーの npm パッケージ名（例：my-api-mcp）
認証方式	はい	API の認証方法（ベアラートークン、API キーなど）
環境変数のプレフィックス	いいえ	環境変数のプレフィックス（例：MYAPI）
スコープ戦略	いいえ	操作をスコープにマッピングする方法（デフォルト：HTTP メソッドに基づく読み取り／書き込み）

出力

出力	説明
MCP サーバー	API 操作ごとに 1 つのツールを備えた TypeScript MCP サーバー
CLI エントリポイント	stdio および SSE トランスポートを備えたコマンドラインインターフェース
スコープ定義	ツールをフィルタリングするスコープベースのアクセス制御
Docker サポート	コンテナー化されたデプロイ用の Dockerfile と compose 設定
ワークフロー設定	MCP 生成用に設定された .speakeasy/workflow.yaml

前提条件

1. Speakeasy CLI がインストールされ、認証済みであること：

speakeasy auth login
# Or for CI/AI agents:
export SPEAKEASY_API_KEY="<your-api-key>"

2. Node.js 20 以降がインストールされていること（生成された MCP サーバー用）。

3. 有効な OpenAPI 仕様（3.0 または 3.1）があること。最初に検証します：

speakeasy lint openapi --non-interactive -s ./openapi.yaml

speakeasy auth login を実行して対話形式で認証するか、SPEAKEASY_API_KEY 環境変数を設定してください。

コマンド

生成には、ワークフロー、オーバーレイ、gen.yaml を設定した後に speakeasy run を使用します。単一のコマンドはありません。以下の手順に従ってください。

# After all config files are in place:
speakeasy run

手順

手順 1：スコープオーバーレイを作成する

プロジェクトのルートに mcp-scopes-overlay.yaml を作成します。ここで、どの API 操作を MCP ツールにするか、また必要なスコープを指定します：

# mcp-scopes-overlay.yaml
openapi: 3.1.0
overlay: 1.0.0
info:
  title: Add MCP scopes
  version: 0.0.0
actions:
  # Enable read operations
  - target: $.paths.*["get","head"]
    update:
      x-speakeasy-mcp:
        scopes: [read]
        disabled: false

  # Enable write operations
  - target: $.paths.*["post","put","delete","patch"]
    update:
      x-speakeasy-mcp:
        scopes: [write]
        disabled: false

  # Disable specific sensitive endpoints (customize as needed)
  # - target: $.paths["/admin/danger-zone"]["delete"]
  #   update:
  #     x-speakeasy-mcp:
  #       disabled: true

手順 2：ワークフロー設定を作成する

.speakeasy/workflow.yaml を作成します：

# .speakeasy/workflow.yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  My-API:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: mcp-scopes-overlay.yaml
    output: openapi.yaml
targets:
  mcp-server:
    target: mcp-typescript
    source: My-API

./openapi.yaml を実際の仕様のパスまたは URL に置き換えてください。

重要： スタンドアロンの mcp-typescript ターゲットを使用してください。enableMCPServer: true を指定した typescript は使用しないでください。埋め込み方式（enableMCPServer フラグ）は非推奨です。

手順 3：gen.yaml を設定する

.speakeasy/gen.yaml を作成します：

# .speakeasy/gen.yaml
configVersion: 2.0.0
generation:
  sdkClassName: MyApiMcp
  maintainOpenAPIOrder: true
  devContainers:
    enabled: true
    schemaPath: ./openapi.yaml
typescript:
  version: 1.0.0
  packageName: my-api-mcp
  envVarPrefix: MYAPI

主な設定：

• workflow.yaml の target: mcp-typescript ― MCP サーバーの生成を開始する設定です
• packageName ― ユーザーが npx で実行する npm パッケージ名です
• envVarPrefix ― 自動生成される環境変数名のプレフィックスです

手順 4：生成する

speakeasy run

AI フレンドリーな出力の場合：

speakeasy run --output console 2>&1 | tail -50

生成した MCP サーバーの使用

CLI の使用方法

# Start with stdio transport (default, for local AI assistants)
npx my-api-mcp mcp start --bearer-auth "YOUR_TOKEN"

# Start with SSE transport (for networked deployment)
npx my-api-mcp mcp start --transport sse --port 3000 --bearer-auth "YOUR_TOKEN"

# Filter by scope (only expose read operations)
npx my-api-mcp mcp start --scope read --bearer-auth "YOUR_TOKEN"

# Mount specific tools only
npx my-api-mcp mcp start --tool users-get-users --tool users-create-user --bearer-auth "YOUR_TOKEN"

CLI オプション

フラグ	説明	デフォルト
--transport	トランスポートの種類：stdio または sse	stdio
--port	SSE トランスポート用のポート	2718
--bearer-auth	API 認証トークン	必須
--server-url	API ベース URL の上書き	仕様から取得
--scope	スコープでフィルタリング（複数回指定可能）	すべてのスコープ
--tool	特定のツールをマウント（複数回指定可能）	すべてのツール
--log-level	ログレベル	info

Claude Desktop の設定

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "--package", "my-api-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

Claude Code の設定

.claude/settings.json に追加するか、claude mcp add を使用します：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "--package", "my-api-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

Docker でのデプロイ

本番環境では、Docker で SSE トランスポートを使用します：

# Build and run
docker-compose up -d

# Configure MCP client to use SSE endpoint
# "url": "http://localhost:32000/sse"

生成されたプロジェクトには Dockerfile と docker-compose.yaml が含まれます。

例

ペットストア API 用の MCP サーバーを生成する完全な例：

# 1. Validate the spec
speakeasy lint openapi --non-interactive -s ./petstore.yaml

# 2. Create scopes overlay
cat > mcp-scopes-overlay.yaml << 'EOF'
openapi: 3.1.0
overlay: 1.0.0
info:
  title: Add MCP scopes
  version: 0.0.0
actions:
  - target: $.paths.*["get","head"]
    update:
      x-speakeasy-mcp:
        scopes: [read]
        disabled: false
  - target: $.paths.*["post","put","delete","patch"]
    update:
      x-speakeasy-mcp:
        scopes: [write]
        disabled: false
EOF

# 3. Create workflow (assumes .speakeasy/ dir exists)
mkdir -p .speakeasy
cat > .speakeasy/workflow.yaml << 'EOF'
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  petstore:
    inputs:
      - location: ./petstore.yaml
    overlays:
      - location: mcp-scopes-overlay.yaml
    output: openapi.yaml
targets:
  mcp-server:
    target: mcp-typescript
    source: petstore
EOF

# 4. Create gen.yaml
cat > .speakeasy/gen.yaml << 'EOF'
configVersion: 2.0.0
generation:
  sdkClassName: PetStoreMcp
  maintainOpenAPIOrder: true
typescript:
  version: 1.0.0
  packageName: petstore-mcp
  envVarPrefix: PETSTORE
EOF

# 5. Generate
speakeasy run

# 6. Test locally
npx petstore-mcp mcp start --bearer-auth "test-token"

期待される出力

Workflow completed successfully.
Generated TypeScript MCP server in ./

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

• src/mcp-server/server.ts -- メインの MCP サーバーファクトリー
• src/mcp-server/tools/ -- API オペレーションごとに 1 つのツール
• src/mcp-server/mcp-server.ts -- CLI エントリーポイント
• src/mcp-server/scopes.ts -- スコープ定義

ベストプラクティス

1. MCP 設定にはオーバーレイを使用する -- ソースの OpenAPI 仕様を直接編集しないでください
2. AI 向けに説明を拡充する -- AI アシスタントがツールの目的を理解できるよう、ドキュメントのオーバーレイを追加してください
3. 実行時にツールをフィルタリングする -- --scope と --tool フラグを使用して、公開する内容を制限してください
4. 環境変数を使用する -- 設定ファイルにトークンをハードコードしないでください
5. 読み取り専用のスコープから始める -- 必要な場合にのみ書き込みスコープを追加してください
6. 専用の MCP パッケージを作成する -- MCP はメインの SDK とは分けてください

してはいけないこと

• ソースの OpenAPI 仕様を変更して x-speakeasy-mcp を追加しないでください -- 代わりにオーバーレイを使用してください
• Claude Desktop や Claude Code の設定ファイルに API トークンをハードコードしないでください -- 環境変数またはシークレットマネージャーを使用してください
• すべてのオペレーションを確認せずに公開しないでください -- 機密性の高い管理エンドポイントは無効にしてください
• 仕様の検証を省略しないでください -- 無効な仕様では、正常に動作しない MCP サーバーが生成されます
• gen.yaml で非推奨の enableMCPServer: true フラグを使用しないでください -- 代わりに workflow.yaml でスタンドアロンの mcp-typescript ターゲットを使用してください
• スコープのオーバーレイなしで生成しないでください -- ツールにスコープ定義がない状態になります
• 生成された MCP サーバーを汎用 SDK として使用しないでください -- AI アシスタントとの連携に特化して設計されています

トラブルシューティング

MCP サーバーが起動しない

症状： npx my-api-mcp mcp start を実行すると、すぐにエラーが発生します。

原因： 認証フラグが指定されていないか、無効です。

対処法：

# Ensure auth flag matches your API's auth scheme
npx my-api-mcp mcp start --bearer-auth "YOUR_TOKEN"

# Check --help for available auth flags
npx my-api-mcp mcp start --help

AI アシスタントにツールが表示されない

症状： MCP サーバーは起動しますが、AI アシスタントにツールが表示されません。

原因： x-speakeasy-mcp 拡張がないか、すべてのオペレーションが無効になっています。

対処法： スコープのオーバーレイが workflow.yaml の overlays: に記載されていること、およびオペレーションの disabled: false が設定されていることを確認してください。

mcp-typescript ターゲットで生成に失敗する

症状： target: mcp-typescript を使用すると、speakeasy run が失敗します。

原因： 通常、仕様の検証に関する問題、workflow の設定漏れ、または mcp-typescript ターゲットではなく非推奨の enableMCPServer フラグを使用していることが原因です。

対処法：

# Validate spec first
speakeasy lint openapi --non-interactive -s ./openapi.yaml

# Ensure workflow.yaml uses target: mcp-typescript (NOT target: typescript with enableMCPServer)
cat .speakeasy/workflow.yaml

# Remove enableMCPServer from gen.yaml if present -- it is deprecated

想定したオペレーションがツールに含まれない

症状： 一部の API オペレーションを MCP ツールとして利用できません。

原因： スコープのオーバーレイの対象になっていないか、明示的に無効化されています。

対処法： mcp-scopes-overlay.yaml のターゲットセレクターを確認してください。パスとメソッドが仕様と一致していることを確認してください。