mcp-builder

MCP Builder

2026-07-28 の安定仕様に準拠して、相互運用可能な MCP 実装を構築します。拡張機能は、プロトコルの中核として保証されたものではなく、ネゴシエーションによって選択されるオプトイン機能として扱ってください。

---

1. 安定版の基準と互換性

• 権威ある安定版の基準は MCP 2026-07-28 です。
• コアリクエストはステートレスかつ自己完結型です。トランスポート接続やプロセスの存続期間から、プロトコルバージョン、クライアントの機能、識別情報、会話、タスクの状態を推測しないでください。
• 複数のリクエストにまたがる状態は、関連するすべてのリクエストで指定される明示的な識別子を介して管理してください。
• プロトコルバージョンと機能をネゴシエーションし、クライアントまたはサーバーがすべてのオプション機能を実装していると想定しないでください。
• 仕様で求められる場合は、以前のピアとの互換性を維持してください。これには、レガシーなリソース未検出エラーコード -32002 を受け入れつつ、現行プロトコルでは無効なパラメーターに対して -32602 を返すことが含まれます。

コアと拡張機能

レイヤー	ステータス	エンジニアリング上のルール
基本プロトコル、バージョン管理、メッセージパターン	安定したコア	すべての実装で必須
リソース、プロンプト、ツール、エリシテーション	オプションのコア機能	使用前に機能を通知し、対応状況を確認する
タスク、MCP 経由の Skills、MCP Apps	拡張機能	オプトインとし、両方のピアによる明示的なサポートを必須とする
ドラフトまたはベンダー拡張機能	実験的／ベンダー固有	アダプターと機能フラグの背後に分離する

ある SDK またはホストがサポートしているというだけで、拡張機能を安定版とみなさないでください。拡張機能独自の公式なステータスとバージョンを確認してください。

---

2. アーキテクチャ

MCP は、ホスト、クライアント、サーバー間で JSON-RPC 2.0 を使用します。

host application
  └─ MCP client / runtime adapter
       ├─ stdio transport
       └─ Streamable HTTP transport
            └─ MCP server
                 ├─ resources
                 ├─ prompts
                 └─ tools

ステートレスなリクエストモデル

すべてのリクエストには、ネゴシエーションされたバージョンで必要なプロトコルメタデータを含める必要があります。2026-07-28 では、予約済みの _meta キーに含めるリクエストごとのプロトコルバージョンとクライアント機能のメタデータが該当します。

サーバーは、プロトコルバージョンと機能を検出するために server/discover を実装する必要があります。クライアントは通常のリクエストの前にこれを呼び出すか、stdio ピアとの後方互換性を確認するためのプローブとして使用できます。

次のことはしないでください。

• stdio プロセスを会話やセッションの境界として使用する。
• 機能や識別情報を確立するために、リクエストの順序に依存する。
• 明示的なハンドルのない、隠れた可変状態を保持する。
• 認可の判断に、クライアント／サーバーが自己申告した情報を使用する。

次のことを行ってください。

• タスク、スレッド、ワークスペース、サブスクリプションのハンドルを明示する。
• すべてのリクエストを個別に検証する。
• 関連のないタスクからのリクエストが交錯しても処理できるようにする。
• 永続的なハンドルのライフサイクル、有効期限、クリーンアップについて説明する。

---

3. トランスポートと認証

トランスポート	典型的な用途	セキュリティの基準
stdio	ローカルプロセスとの統合	認証情報を環境から読み取り、プロセスとファイルシステムへのアクセスを制限する
Streamable HTTP	リモートまたは共有サービス	MCP HTTP 認可フレームワークを使用し、該当する場合はオリジンを検証し、ネットワーク境界を適用する

WebSocket は、別途ネゴシエーションされた拡張機能またはベンダーアダプターで定義されていない限り、標準の MCP トランスポートではありません。

トランスポートに関する懸念をプロトコルのセマンティクスに持ち込まないでください。再接続やプロセスの置き換えによって、明示的な永続ハンドルで表現された論理状態が失われてはなりません。

---

4. スキーマの設計と検証

MCP では、$schema が指定されていない場合、デフォルトで JSON Schema 2020-12 を使用します。実装ではこの方言をサポートする必要があり、追加の方言がある場合はその旨を説明してください。

ツールの入力スキーマ

• ツール引数のルートにはオブジェクトを使用してください。
• すべてのプロパティに、明確で動作を示す説明を付けてください。
• 必須フィールドを明示的に宣言してください。
• 前方互換性のためにオープンなオブジェクトが必要でない限り、範囲を絞った列挙型、制限値、形式、および additionalProperties: false を優先してください。
• スキーマと各呼び出しのペイロードの両方を検証してください。

ツール出力スキーマ

利用側で型が定義され、予測可能な結果が必要な場合は、構造化コンテンツと outputSchema を使用してください。人が読むテキストは簡潔にし、自動化では構造化出力を信頼できる唯一の情報源として扱ってください。

$ref とバリデーターの安全性

• ネットワーク上の $ref 値を自動的に参照解決しないでください。
• リモート参照解決を明示的に有効にする場合は、ホストの許可リストを使用し、ループバック、リンクローカル、プライベートアドレスを拒否し、タイムアウトとレスポンスサイズの上限を設定し、機密情報を含めずに解決済み URI をログに記録してください。
• 未解決の外部参照があるスキーマは、制約が緩いものとして扱わず、拒否してください。
• 合成キーワードや再帰参照によるサービス拒否を防ぐため、スキーマの深さ、サブスキーマの総数、検証時間に上限を設定してください。

---

5. ツール、リソース、プロンプトの設計

ツール

• 明確なアクション名を使い、責務を一つに絞ってください。
• 役立つ場合は、読み取り専用、破壊的、冪等、オープンワールドの動作をアノテーションで示してください。ただし、サーバー自体が信頼できる場合を除き、アノテーションは信頼できないヒントとして扱ってください。
• 重大な結果を伴うアクションには、ユーザーの明示的な承認を求めてください。
• 内部のスタックトレースや機密情報を含めず、安定した機械可読エラーを返してください。

リソース

• 安定した URI と MIME タイプを使用してください。
• 検出用メタデータとリソースのコンテンツを分離してください。
• サーバー接続ごとだけでなく、リソースごとに認可を適用してください。
• ユーザーの同意なく、リソースデータを別のサーバーやモデルに密かに転送しないでください。

プロンプト

• プロンプトは隠れた権限ではなく、ユーザーに表示されるテンプレートとして扱ってください。
• ツールの権限とポリシーの適用は、プロンプトのテキストの外部で行ってください。
• プロンプトの引数を検証し、生成されるメッセージに含まれるデータソースを明示してください。

---

6. セキュリティ要件

1. 同意と最小権限 — 必要なデータのみを公開し、ツールの実行やデータ共有の前に明示的な承認を得てください。
2. 信頼できないメタデータ — ツールの説明、アノテーション、クライアント情報、サーバー情報、モデルが生成した引数を、認可の根拠として使用しないでください。
3. 入力と出力の検証 — 信頼境界でスキーマ、引数、構造化された結果、URI、コンテンツタイプを検証してください。
4. シークレットの取り扱い — 認証情報は環境変数またはシークレットマネージャーから読み込んでください。実際のキーをリポジトリの設定、ログ、トレース、プロンプト、エラーペイロードに決して含めないでください。
5. ネットワーク制御 — リモートのスキーマやリソースの取得において、SSRF、リダイレクトの悪用、過大なレスポンス、遅いレスポンスを防いでください。
6. 実行の分離 — サブプロセスとファイルシステムアクセスをサンドボックス化してください。明示的なパス許可を使用し、アーカイブやシンボリックリンクによる範囲外へのアクセスを拒否してください。
7. 監査可能性 — セキュリティ上重要な判断、承認、ツールの識別情報、結果のステータスを記録してください。ただし、機密性の高いペイロードを不必要に保存しないでください。

---

7. 拡張機能

拡張機能はコアプロトコルとは独立してネゴシエーションされます。

拡張機能	用途	安全対策
タスク	長時間実行される作業、ポーリング、永続的なハンドル、実行中の入力	古い実験的なタスク API は使用せず、拡張機能をネゴシエーションしてください
MCP のスキル	検索可能な構造化されたエージェント向け指示	スキルのコンテンツを信頼できない入力として扱い、ホストのポリシーを適用してください
MCP Apps	会話内に表示されるインタラクティブな UI	オリジン、コンテンツ、データアクセス、アクション権限を制限してください

アダプターは、拡張機能がない場合でも適切に失敗しなければなりません。機能の同等性を維持するために、セキュリティ要件を暗黙のうちに緩和しないでください。

---

8. 非推奨機能と移行

2026-07-28 の仕様では、互換性を維持する期間を設けつつ、従来のルート、サンプリング、ロギング形式を非推奨としています。互換性を突然削除しないでください。ただし、新しいアーキテクチャを非推奨の形式に基づいて設計することは避けてください。

2025 年当時の実装からの移行チェックリスト

• 接続スコープのセッションと initialize ハンドシェイクを、リクエストごとのステートレスなメタデータに置き換えます。
• バージョンと機能の選択に server/discover を実装するか、利用します。
• 永続状態を、明示的なタスク、スレッド、ワークスペース、またはアプリケーションのハンドルで管理します。
• ネゴシエートしたプロトコルバージョンとクライアント機能を、すべてのリクエストで送信し、検証します。
• スキーマ検証を、デフォルトで JSON Schema 2020-12 にアップグレードします。
• ネットワーク経由の $ref 解決をデフォルトで無効にし、検証リソースの上限を設けます。
• 実験的な Tasks の利用を、ネゴシエートした Tasks 拡張機能に移行します。
• 従来の -32002 リソース未検出レスポンスを受け入れつつ、現在のエラーセマンティクスで出力します。
• 古いサーバーで resultType が欠落している場合は "complete" として扱い、現行バージョンの結果では必須とします。
• roots、sampling、logging の各統合について、文書化された代替機能と非推奨化のスケジュールを確認します。
• 少なくとも 1 つの古いピアと 1 つの 2026-07-28 ピアを対象とした相互運用テストを追加します。

---

9. テストマトリクス

テスト	期待される証拠
コントラクト	無効な JSON-RPC、メタデータの欠落、未サポートのバージョン／機能、スキーマ方言の処理
ステートレス性	リクエストのインターリーブ、再接続、プロセスの再利用、明示的なハンドルによる復旧
スキーマセキュリティ	外部 $ref、再帰的／合成スキーマ、深度／件数／時間の上限
認可	リソース／ツールへのアクセス拒否、承認ゲート、認証情報の分離
拡張機能のネゴシエーション	拡張機能なし、バージョン不一致、機能有効化、適切なフォールバック
互換性	現行のピアと、サポート対象の古いプロトコルリビジョン
障害処理	タイムアウト、キャンセル、部分的な結果、構造化エラー、シークレットの漏えいなし

---

10. レビューチェックリスト

• 安定したプロトコルバージョンと拡張機能のステータスが文書化されています。
• リクエストはステートレスであり、リクエスト間の状態には明示的なハンドルを使用します。
• オプションの操作を行う前に、機能をネゴシエートして確認します。
• JSON Schema 2020-12 をサポートし、バリデーターのリソース使用量に上限を設けています。
• ネットワーク経由の $ref 解決はデフォルトで無効です。
• ツールの注釈を認可の根拠として信頼していません。
• ユーザーの承認、最小権限、シークレットの取り扱い、実行の分離を、プロンプトの外部で徹底しています。
• 非推奨の機能について、互換性と移行の計画があります。
• コントラクト、セキュリティ、拡張機能、バージョン間の各テストに合格しています。