build-mcp-server

MCP サーバーの構築

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

まず Claude 固有のコンテキストを読み込みます。 MCP 仕様は汎用的なものですが、Claude には追加の認証方式、審査基準、制限があります。質問への回答やひな形の作成を始める前に、https://claude.com/docs/llms-full.txt（Claude コネクタードキュメントの完全版エクスポート）を取得し、Claude の実際の制約を踏まえてガイドしてください。

フェーズ 1 の質問への回答がそろうまでは、ひな形の作成を始めないでください。ユーザーの最初のメッセージですでに回答がそろっている場合は、その旨を確認し、すぐに推奨案を提示してください。

---

フェーズ 1 — ユースケースを確認する

以下の質問を会話形式で尋ねます（1 つのメッセージにまとめ、1 問ずつ尋ねないでください）。ユーザーがすでに伝えた内容に合わせて、質問の表現を調整してください。

1. 何に接続しますか？

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

2. 誰が使いますか？

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

3. いくつの異なるアクションを公開しますか？

これはツール設計のパターンを決めます — フェーズ 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 を参照してください

---

フェーズ 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。任意のホストで実行できます）

エリシテーション（構造化入力、UI の構築不要）

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

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

ネストされたデータや複雑なデータ、スクロールや検索が可能なリスト、ビジュアルプレビュー、ライブ更新が必要な場合は、build-mcp-app ウィジェットに切り替えてください。

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

前述の機能に加えて、UI リソースを利用できます。チャット内にインタラクティブなウィジェットを表示します。検索可能なリッチなピッカー、グラフ、ライブダッシュボード、ビジュアルプレビューなどを利用できます。一度構築すれば、Claude と ChatGPT の両方で表示できます。

次の場合に選択してください： エリシテーションのフラットフォームという制約が合わず、カスタムレイアウト、大規模な検索可能リスト、ビジュアルコンテンツ、ライブ更新が必要な場合。

通常はリモートで動作しますが、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 段落で改めて記載します。

---

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

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

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

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

---

フェーズ 6 — Claude でテストして公開する

サーバーが動作したら、次の手順を実行します。

1. 実際の Claude でテストします。Settings → Connectors でサーバー URL をカスタムコネクタとして追加します（ローカルサーバーには Cloudflare トンネルを使用してください）。Claude は初期化時に clientInfo.name: "claude-ai" として自身を識別します。→ https://claude.com/docs/connectors/building/testing
2. 提出前チェックリストを実行します — 読み取り／書き込みツールの分割、必須アノテーション、名前の制限、プロンプトインジェクションのルールを確認します。→ https://claude.com/docs/connectors/building/review-criteria
3. Anthropic Directory に提出します。 → https://claude.com/docs/connectors/building/submission
4. この MCP をスキルでラップしたプラグインの公開を推奨します — ほとんどのパートナーは両方を公開しています。→ https://claude.com/docs/connectors/building/what-to-build

---

クイックリファレンス：判断マトリクス

シナリオ	デプロイ	ツールパターン
小規模な 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 — 指示、サンプリング、ルート、ログ記録、進捗、キャンセル
• references/versions.md — バージョン依存の主張の記録（更新時に確認）