TypeScript開発者が試すOrval活用術：OpenAPIからMCPサーバーを自動生成しClaudeでAPIを呼び出すまで

🐾 はじめに

こんにちは、砂川(@misdo_tabeyo)です。

普段は『弁護士ドットコムLIBRARY』と『BUSINESS LAWYERS LIBRARY』というサービスでフロントエンド開発を担当しています。これらのサービスでは、Orval を利用して OpenAPI からAPIクライアントやZodのバリデーションスキーマを生成しています。

そんなOrvalに最近、Model Context Protocol (MCP) サーバーの生成機能が追加された と知り、早速試してみました。

MCP は LLM（大規模言語モデル）アプリケーションと外部ツール・データソースを接続するための標準プロトコルであり、AI エージェントと API のやり取りを仲介します。

本記事では、サンプルの OpenAPI スキーマを使い、Stoplight の Prism でモックサーバーを立ち上げ、Orval で MCP サーバーを生成し、Claude Desktop から呼び出すまでの手順を解説します。

このチュートリアルでは以下を学びます：

• OpenAPI仕様に基づいたモックAPIサーバー（Prism）を用意する
• OrvalでMCPサーバーコードを自動生成する
• Claude DesktopとローカルのMCPサーバーを接続し、自然言語で呼び出せる状態にする

📦 プロジェクトセットアップ

Node.js の確認

Node.js v18 以上を推奨：

node -v

プロジェクト初期化

mkdir orval-mcp-example
cd orval-mcp-example
npm init -y

依存パッケージのインストール

npm install -D typescript ts-node @types/node
npm install -D orval @modelcontextprotocol/sdk
npm install -D @stoplight/prism-cli

🧾 OpenAPI定義ファイルの作成

プロジェクト直下に demo-api.yaml という名前で以下のOpenAPI仕様を保存してください：

openapi: 3.1.0
info:
  title: Demo API
  version: 1.0.0
paths:
  /todos:
    get:
      summary: Get todo list
      responses:
        '200':
          description: List of todos
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string

🛠 Orval設定ファイルの作成

プロジェクト直下に orval.config.ts を作成：

import { defineConfig } from 'orval';

export default defineConfig({
  demo: {
    input: {
      target: './demo-api.yaml',
    },
    output: {
      mode: 'single',
      client: 'mcp',
      baseUrl: 'http://localhost:4010',
      target: 'src/handlers.ts',
      schemas: 'src/http-schemas',
    },
  },
});

⚙️ TypeScriptコンパイル設定

tsconfig.json を以下のように作成します：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "exclude": ["orval.config.ts"]
}

🧬 コード生成

以下を実行して、 demo-api.yaml をもとにOrvalでコードを生成します：

npx orval

生成されたコードの説明

ファイル名	説明
http-schemas/	OpenAPI のリクエスト/レスポンススキーマ定義
http-client.ts	fetch ベースの API クライアント
handlers.ts	MCP ツールとして動作するハンドラー
server.ts	MCP サーバーの設定と起動コード
tool-schemas.zod.ts	各ツールの入力バリデーションスキーマ（Zod）

⚒️ ビルド

Claude Desktop でMCPサーバーを利用するために生成されたコードをビルドします。

npx tsc

これで dist/server.js が生成されます。

🌐 モックAPIサーバーの起動

OpenAPI定義をもとにPrismでモックAPIサーバーを起動：

npx prism mock demo-api.yaml -p 4010

別ターミナルで確認：

curl http://localhost:4010/todos

サンプルデータが返れば成功です。

⚙️ Claude Desktop に MCPツールとして登録

Claudeの設定ファイルを開く

1. Claude Desktop を起動
2. メニューバー →「Claude」→「Settings」
3. 左側「Developer」→「Edit Config」

設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json）が開きます。

claude_desktop_config.json にツールを登録

{
  "mcpServers": {
    "demo-server": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/yourname/path/to/orval-mcp-example/dist/server.js"]
    }
  }
}

• "command" には which node で取得した絶対パスを指定してください（例：/usr/local/bin/node）
• "args" は server.js の絶対パスです

保存後、Claude を完全に再起動します（Cmd + Q）。

✅ 動作確認

Claude に以下のように話しかけて、ローカルのMCPサーバーが呼ばれていれば成功です：

• 「やることリストに登録されているやることを教えて」 → /todos が呼び出される

Claudeの出力ログに GET /todos が表示されていれば、MCP連携は成功しています。

✅ まとめ

ステップ	内容
OpenAPI定義作成	demo-api.yaml でMCP対応の仕様を書く
モックAPI起動	PrismでOpenAPI仕様通りのレスポンスを用意
Orvalで生成	npx orval でTypeScriptのMCPサーバーを自動生成
TypeScriptビルド	npx tsc で dist/server.js を生成
Claude連携	claude_desktop_config.json にサーバー起動情報を登録し、ツールとして使えるようにする

🔗 参考リンク

• Orval MCPガイド
• Claude公式
• MCP仕様
• Prism CLI
• OpenAPI公式