build-mcp-server

MCP サーバーを構築する

Claude とシームレスに連携する MCP サーバーの設計と構築を、開発者向けに案内します。MCP サーバーにはさまざまな形態があり、最初に誤った形を選ぶと、後で大幅な書き直しが必要になります。まず行うべきことは、コードを書くことではなく、要件を把握することです。

Phase 1 の質問への回答を得るまでは、スキャフォールディングを始めないでください。ユーザーの最初のメッセージにすでに回答が含まれている場合は、その旨を確認し、すぐに推奨案を提示してください。

適用する場面

• ユーザーが MCP サーバーの構築、作成、またはスキャフォールディングを依頼した場合
• ユーザーが Claude で使う REST／GraphQL API のラッパーを作成したい場合
• ユーザーが MCP 経由でツール、リソース、またはプロンプトを公開したい場合
• ユーザーがデプロイモデル（リモート HTTP、MCPB、ローカル stdio）の選択を検討している場合
• ユーザーが MCP 連携用のツールスキーマを設計している場合

ワークフローの概要

Phase 1: Discovery → Phase 2: Deployment model → Phase 3: Tool pattern → Phase 4: Framework → Phase 5: Scaffold

各フェーズで設計の選択肢を絞り込みます。Phase 5 の後、適切なスキャフォールドのリファレンスまたは関連スキルに引き継ぎます。

前提条件

• TypeScript の場合： Node.js >= 18、npm
• Python の場合： Python >= 3.10、pip
• テスト： npx（npm に同梱）— scripts/test-server.sh と MCP Inspector で使用します

---

Phase 1 — ユースケースを詳しく確認する

これらの質問は会話形式で尋ねてください（一度のメッセージにまとめ、1つずつ尋問するように聞かないでください）。ユーザーがすでに伝えた内容に合わせて、質問の表現を調整してください。

1. 何に接続しますか？

接続先…	想定される方向性
クラウド API（SaaS、REST、GraphQL）	リモート HTTP サーバー
ローカルプロセス、ファイルシステム、またはデスクトップアプリ	MCPB またはローカル stdio
ハードウェア、OS レベルの API、またはユーザー固有の状態	MCPB
外部接続なし — 純粋なロジック／計算	どちらでも可 — デフォルトはリモート

2. 誰が使いますか？

• 自分／チームだけが、自分たちのマシンで使う → ローカル stdio で問題ありません（プロトタイプを作るのに最も簡単です）
• インストールする人なら誰でも使う → リモート HTTP（強く推奨）、またはローカルである必要がある場合は MCPB
• UI ウィジェットを使いたい Claude デスクトップユーザー → MCP アプリ（リモートまたは MCPB）

3. 公開する個別のアクションはいくつありますか？

これによってツール設計のパターンが決まります — Phase 3 を参照してください。

• 約15未満のアクション → アクションごとに1つのツール
• 数十から数百のアクション（例：大規模な API 群をラップする場合） → 検索＋実行パターン

4. ツールの実行中にユーザー入力が必要ですか？ または豊富な表示が必要ですか？

• シンプルな構造化入力（リストから選ぶ、値を入力する、確認する） → Elicitation — 仕様に組み込まれており、UI コードは不要です。ホストのサポートは順次導入中です（Claude Code ≥2.1.76）— 必ず機能チェックとフォールバックを併用してください。references/elicitation.md を参照してください。
• リッチ／ビジュアル UI（グラフ、検索機能付きカスタムピッカー、ライブダッシュボード） → MCP アプリのウィジェット — iframe ベースで、@modelcontextprotocol/ext-apps が必要です。build-mcp-app スキルを参照してください。
• どちらも不要 → テキスト／JSON を返す通常のツール

5. 上流サービスではどの認証方式を使いますか？

• なし／API キー → 簡単です
• OAuth 2.0 → CIMD（推奨）または DCR をサポートするリモートサーバーが必要です。references/auth.md を参照してください

---

Phase 2 — デプロイモデルを推奨する

回答に基づいて、1つの方針を推奨してください。明確な見解を示してください。選択肢の優先順位は次のとおりです。

リモート streamable-HTTP MCP サーバー（デフォルトの推奨）

streamable HTTP 経由で MCP を提供するホスト型サービスです。クラウド API をラップする場合は、推奨される方法です。

推奨する理由：

• インストール時の手間がありません — ユーザーは URL を追加するだけです
• 1つのデプロイで全ユーザーに対応でき、アップグレードも管理できます
• OAuth フローが適切に動作します（サーバーがリダイレクト、DCR、トークン保存に対応できます）
• Claude デスクトップ、Claude Code、Claude.ai、およびサードパーティの MCP ホストで動作します

サーバーがユーザーのローカルマシンにアクセスする必要がある場合を除き、この方法を選んでください。

→ 最速でデプロイ： Cloudflare Workers — references/deploy-cloudflare-workers.md（2つのコマンドで URL を公開） → 移植可能な Node／Python： references/remote-http-scaffold.md（Express または FastMCP を使用し、任意のホストで実行）

Elicitation（構造化入力、UI 構築不要）

ユーザーに確認してもらう、選択肢を選んでもらう、または短いフォームに入力してもらうだけなら、Elicitationを使えばUIコードは一切不要です。サーバーがフラットなJSONスキーマを送信し、ホストがネイティブフォームを表示します。仕様に準拠しており、追加パッケージも不要です。

**注意点：**ホスト側のサポートは始まったばかりです（Claude Codeはv2.1.76で提供開始、Desktopは未確認）。クライアントがこの機能に対応していることを通知していない場合、SDKはエラーをスローします。必ず最初にclientCapabilities.elicitationを確認し、フォールバックも用意してください。標準的な実装パターンについてはreferences/elicitation.mdを参照してください。これは仕様に準拠した正しい方法であり、ホスト側の対応範囲は今後広がっていきます。

ネストされたデータや複雑なデータ、スクロールまたは検索できるリスト、ビジュアルプレビュー、ライブ更新が必要な場合は、build-mcp-appウィジェットに移行してください。

MCP アプリ（リモートHTTP＋インタラクティブUI）

上記と同じですが、UIリソースが加わります。チャット内にインタラクティブなウィジェットが表示されます。検索可能な高機能ピッカー、グラフ、ライブダッシュボード、ビジュアルプレビューを利用できます。一度作成すれば、Claude と ChatGPTの両方で表示できます。

**次の場合はこちらを選んでください：**Elicitationのフラットフォームの制約に合わず、カスタムレイアウト、大規模な検索可能リスト、ビジュアルコンテンツ、ライブ更新が必要な場合。

通常はリモートで動作しますが、UIからローカルアプリを操作する必要があれば、MCPBとして配布できます。

→ **build-mcp-app**スキルに引き継いでください。

MCPB（バンドルされたローカルサーバー）

ランタイムと一緒にパッケージ化されたローカルMCPサーバーです。ユーザーはNode/Pythonをインストールする必要がありません。ローカルサーバーを配布するための正式な方法です。

**次の場合はこちらを選んでください：**サーバーをユーザーのマシン上で実行する必要がある場合。ローカルファイルの読み取り、デスクトップアプリの操作、localhostのサービスとの通信、またはOSレベルのアクセスが必要な場合などです。

→ **build-mcpb**スキルに引き継いでください。

ローカルstdio（npx / uvx）— 配布には非推奨

ユーザーのマシン上でnpx / uvxを使って起動するスクリプトです。個人用ツールやプロトタイプには適しています。配布には不向きです。ユーザーは適切なランタイムを用意する必要があり、更新をプッシュできず、配布経路はClaude Codeプラグインに限られます。

移行の足がかりとしてのみ推奨してください。ユーザーが希望する場合は、ひな形を作成したうえで、MCPBへのアップグレード経路も説明してください。

---

フェーズ3 — ツール設計パターンを選ぶ

すべてのMCPサーバーはツールを公開します。ツールの切り分け方は、多くの人が想像する以上に重要です。ツールのスキーマはClaudeのコンテキストウィンドウに直接入ります。

パターンA：アクションごとに1つのツール（小規模なサーフェス）

アクションの種類が少ない場合（約15未満）は、それぞれに明確な説明と厳密なスキーマを備えた専用ツールを用意します。

create_issue    — Create a new issue. Params: title, body, labels[]
update_issue    — Update an existing issue. Params: id, title?, body?, state?
search_issues   — Search issues by query string. Params: query, limit?
add_comment     — Add a comment to an issue. Params: issue_id, body

**効果がある理由：**Claudeはツール一覧を一度読むだけで、何ができるかを正確に把握できます。探索のための追加往復は不要です。各ツールのスキーマによって入力が正確に検証されます。

**特に有効な場合：**1つ以上のツールがインタラクティブなウィジェット（MCPアプリ）を提供するときです。各ウィジェットを1つのツールに自然に結び付けられます。

パターンB：検索＋実行（大規模なサーフェス）

大規模なAPI（数十から数百のエンドポイント）をラップする場合、すべての操作をツールとして列挙するとコンテキストウィンドウを圧迫し、モデルの性能が低下します。代わりに、2つのツールを公開します。

search_actions  — Given a natural-language intent, return matching actions
                  with their IDs, descriptions, and parameter schemas.
execute_action  — Run an action by ID with a params object.

サーバーはカタログ全体を内部に保持します。Claudeが検索して選択し、実行します。コンテキストは軽量に保たれます。

**ハイブリッド：**最もよく使われる3〜5個のアクションは専用ツールにし、利用頻度の低いその他の操作は検索／実行の背後に置きます。

→ スキーマの例と説明文の書き方についてはreferences/tool-design.mdを参照してください。

---

フェーズ4 — フレームワークを選ぶ

次の2つから推奨してください。他にもありますが、MCP仕様への対応範囲とClaudeとの互換性が最も優れています。

フレームワーク	言語	使用する場面
公式TypeScript SDK（@modelcontextprotocol/sdk）	TS/JS	デフォルトの選択肢です。仕様への対応範囲が最も広く、新機能も最初に利用できます。
FastMCP 3.x（PyPIのfastmcp）	Python	ユーザーがPythonを希望する場合、またはPythonライブラリをラップする場合に適しています。デコレーターベースで、定型コードが非常に少なくて済みます。これはjlowinのパッケージであり、公式のmcp SDKに同梱されている凍結版のFastMCP 1.0ではありません。

ユーザーがすでに使いたい言語やスタックを決めている場合は、それに合わせてください。どちらも同一のワイヤープロトコルを生成します。

---

フェーズ 5 — スキャフォールドを作成して引き継ぐ

4 つの決定（デプロイモデル、ツールパターン、フレームワーク、認証）が固まったら、次のいずれか 1 つを行います。

1. リモート HTTP、UI なし → references/remote-http-scaffold.md（移植性重視）または references/deploy-cloudflare-workers.md（最速でデプロイ）を使って、ここでスキャフォールドを作成します。このスキルで作業を完了できます。
2. MCP アプリ（UI ウィジェット） → ここまでの決定事項をまとめてから、build-mcp-app スキルを読み込みます。
3. MCPB（ローカルバンドル） → ここまでの決定事項をまとめてから、build-mcpb スキルを読み込みます。
4. ローカル stdio プロトタイプ → ここでスキャフォールドを作成します（最も簡単なケース）。MCPB へのアップグレードパスを示します。

引き継ぐ際は、次のスキルで同じ質問を繰り返さずに済むよう、設計概要を 1 段落で改めて伝えてください。

サーバーを検証する

スキャフォールドの作成後、サーバーが正しく応答することを検証します。

# Start the server first (e.g. npx tsx src/server.ts or python server.py)
# Then smoke-test it:
bash scripts/test-server.sh http://localhost:3000/mcp

テストスクリプトは MCP Inspector 経由で tools/list を呼び出し、サーバーが少なくとも 1 つのツールを返すことを確認します。このテストに合格すれば、サーバーは正しく接続されています。

---

ツール以外の要素 — その他のプリミティブ

ツールは、サーバーの 3 つのプリミティブのうちの 1 つです。ほとんどのサーバーはツールから始まり、ほかのプリミティブを必要としませんが、これらの存在を知っておけば、車輪の再発明を防げます。

プリミティブ	実行するユーザー	使用する場面
リソース	ホストアプリ（Claude ではありません）	ドキュメント／ファイル／データを閲覧可能なコンテキストとして公開する
プロンプト	ユーザー（スラッシュコマンド）	定型ワークフロー（「/summarize-thread」）
エリシテーション	サーバー（ツール実行中）	UI を構築せずにユーザーへ入力を求める
サンプリング	サーバー（ツール実行中）	ツールのロジックで LLM 推論が必要な場合

→ references/resources-and-prompts.md、references/elicitation.md、references/server-capabilities.md

---

クイックリファレンス：決定マトリックス

シナリオ	デプロイ	ツールパターン
小規模な SaaS API をラップする	リモート HTTP	アクションごとに 1 つ
大規模な SaaS API（エンドポイント 50 個以上）をラップする	リモート HTTP	検索 + 実行
リッチフォーム／ピッカーを備えた SaaS API	MCP アプリ（リモート）	アクションごとに 1 つ
ローカルデスクトップアプリを操作する	MCPB	アクションごとに 1 つ
チャット内 UI を備えたローカルデスクトップアプリ	MCP アプリ（MCPB）	アクションごとに 1 つ
ローカルファイルシステムを読み書きする	MCPB	実行面による
個人用プロトタイプ	ローカル stdio	最速の方法

---

参考ファイル

該当するフェーズに進んだときに参照してください。事前に読む必要はありません。

• references/remote-http-scaffold.md — TS SDK と FastMCP で作る最小限のリモートサーバー
• references/deploy-cloudflare-workers.md — 最速のデプロイ方法（Workers ネイティブのスキャフォールド）
• references/tool-design.md — Claude が適切に理解できるツールの説明とスキーマの作成方法
• references/auth.md — OAuth、CIMD、DCR、トークン保存のパターン
• references/resources-and-prompts.md — ツール以外の 2 つのプリミティブ
• references/elicitation.md — 仕様に準拠したツール実行中のユーザー入力（機能確認 + フォールバック）
• references/server-capabilities.md — Instructions、サンプリング、ルート、ロギング、進行状況、キャンセル
• references/versions.md — バージョン依存の主張をまとめた一覧（更新時に確認）