mcp-expert

MCP エキスパート

概要

Model Context Protocol のエコシステムを構築、管理するための決定版リソースです。サーバー開発やトランスポートの設定から、セキュリティ、エリシテーション、非同期タスクの実行まで、ライフサイクル全体を網羅します。トークン使用量を最小限に抑え、LLM の精度を最大限に高める、エージェントファーストのツールインターフェースを設計します。

使用する場面： MCP サーバーの構築、ツールインターフェースの設計、トランスポート（Stdio／Streamable HTTP）の設定、OAuth 2.1 の実装、接続のトラブルシューティング、サーバー起点のユーザーとの対話におけるエリシテーションの利用。

使用しない場面： アプリケーションレベルのビジネスロジック、MCP 以外の API 設計、フロントエンドの UI コンポーネント、MCP に関係しない一般的な HTTP API 開発。

クイックリファレンス

パターン	API／アプローチ	主なポイント
成果指向のツール	単一呼び出しの操作	会話のように複数のステップを重ねる API を避けます
引数のフラット化	説明付きのフラットな Zod スキーマ	モデルの幻覚を減らします
段階的開示	大きなデータには mcp:// URI を返す	エージェントは resources/read で部分的に読み取ります
再試行可能なツール	retry_with の提案を返す	不正な入力を LLM が自己修正できるようにします
役立つエラー	修正方法を示す説明的な文字列	生の例外やスタックトレースは決して返しません
ページネーション	has_more と next_cursor のメタデータ	1 回の呼び出しで取得するレコードは最大 20～50 件
構造化出力	outputSchema の JSON Schema	プログラムで利用できる型付きのツール結果
Stdio トランスポート	ローカルツール、ログは stderr のみ	JSON-RPC 以外は決して stdout に書き込みません
Streamable HTTP	リモート／クラウドツール、単一エンドポイント	非推奨の SSE トランスポートに代わるもの
PKCE を使用する OAuth 2.1	エンタープライズデータへのアクセス	MCP サーバーはリソースサーバーであり、認証サーバーではありません
エリシテーション	サーバー起点のユーザー入力	フラットなスキーマはフォームに対応し、応答状態は 3 種類です
非同期タスク	tasks/get、tasks/cancel	長時間実行される操作はタスクハンドルを返します
ケイパビリティスコープ	read:docs、write:code、admin:users	権限の境界を細かく設定できます
HITL ゲート	confirmation_required フラグ	破壊的な操作には手動承認が必要です
URL エリシテーション	認証情報の安全な収集	機密情報の入力のため、ユーザーをブラウザーにリダイレクトします
拡張機能	名前空間付きのケイパビリティネゴシエーション	仕様をフォークせずにオプション機能を追加できます
ツールを使ったサンプリング	サーバー起点の LLM リクエスト	サーバー側のエージェントループを可能にします
MCP Inspector	npx @modelcontextprotocol/inspector	LLM なしでツールを対話的にテストできます
単体テスト	InMemoryTransport と Vitest	モッククライアントでツールハンドラーをテストします
評価フレームワーク	スキーマ、エラー、ページネーションのアサーション	LLM での利用に向けてツールの品質を検証します
ツールコントラクトテスト	スキーマフィールドの説明、エッジケース	すべてのフィールドを説明し、オプションパラメーターを処理します
CI スモークテスト	GitHub Actions と Inspector CLI	ビルド、テスト、トランスポートのヘルスチェックを自動化します

仕様バージョン

現在の MCP 仕様は 2025-11-25 です。主なマイルストーン：

• 2025-03-26：Streamable HTTP トランスポート（単独の SSE を非推奨化）、ツールアノテーション
• 2025-06-18：構造化ツール出力、エリシテーション、OAuth 認証サーバーの分離
• 2025-11-25：非同期タスク、拡張フレームワーク、ツールを使用したサンプリング、CIMD 認証、サーバー検出

オンボーディングプロトコル

エージェントに新しい機能が必要な場合：

1. 検証：必要な MCP サーバーがすでに有効になっているか確認します
2. 案内：見つからない場合は、ユーザーに直接インストール手順を提示します
3. 設定：可能な場合は uvx または npx を使い、インストール不要で実行します

よくある間違い

間違い	正しいパターン
多数の往復を必要とする会話的な API を設計する	1 回の呼び出しでタスクを完了する、成果重視のツールを構築します
stdout へのログ出力で Stdio トランスポートを妨げる	トランスポートチャネルをクリーンに保つため、stderr のみにログを出力します
生の例外やスタックトレースを LLM に返す	修正案を含む、役立つエラーメッセージを返します
数十個のツールを備えたモノリシックなサーバーを構築する	見つけやすさとメンテナンス性のため、サーバーのツール数を 5～15 個に抑えます
新しいサーバーに非推奨の HTTP+SSE トランスポートを使う	リモートサーバーには Streamable HTTP を使います（単一エンドポイント、任意の SSE）
MCP サーバーの設定にシークレットをハードコードする	機密値にはすべて環境変数マッピングを使用します
1 回のツール呼び出しで大規模なデータセットを返す	大規模なデータにはページネーション（20～50 件）またはリソース URI を使います
MCP サーバー内に認証サーバーを実装する	MCP サーバーは OAuth 2.1 リソースサーバーのみとして動作し、認証は外部に委譲します
曖昧なツールの説明により LLM にハルシネーションを起こさせる	ツールの説明フィールドに使用例と厳密な制約を追加します
長時間の処理を同期的にブロックする	タイムアウトしきい値を超える処理には、非同期タスクハンドルを返します
受信したトークンを上流 API に渡す	トークンをローカルで検証し、混乱した代理人攻撃を避けるため転送しないでください
エリシテーションでシークレットを要求する	認証情報の収集には URL モードのエリシテーションまたは専用の OAuth フローを使います

MCP プリミティブ

MCP サーバーは、次の 3 つのコアプリミティブ型をクライアントに公開します。

• ツール：タスクを実行するために LLM が呼び出す、モデル制御のアクション（関数呼び出し）
• リソース：クライアントが必要に応じて読み取る、mcp:// URI 経由で公開されるアプリケーション制御のデータ
• プロンプト：特定のワークフローに構造化されたコンテキストを提供する、ユーザー制御のテンプレート

サーバーは、initialize ハンドシェイクでのケイパビリティネゴシエーション中に、サポートするプリミティブを宣言します。2025 年 11 月の仕様では、非同期実行向けの実験的なプリミティブとして タスク が追加されています。

トランスポートの選択

シナリオ	トランスポート	備考
ローカル CLI ツール	Stdio	起動が最速で、ネットワークのオーバーヘッドがありません
リモート／クラウドサーバー	Streamable HTTP	単一エンドポイント、任意の SSE ストリーミング
レガシーリモート	HTTP+SSE	2025-03-26 以降非推奨です。Streamable HTTP に移行してください

クライアントは、可能な限り Stdio をサポートしてください。Streamable HTTP は、任意の Mcp-Session-Id ヘッダーを介して、ステートレスおよびステートフルの両方のサーバー実装をサポートします。

委任

• 既存の MCP サーバー設定を調査・監査する：Explore エージェントを使用して、稼働中のサーバーを確認し、接続を検証して、不足している機能を特定します
• 検証と認証を備えた新しい MCP サーバーを構築・デプロイする：Task エージェントを使用して、サーバーのひな形を作成し、Zod による検証を実装して、OAuth を設定します
• マルチエージェントワークフロー向けの MCP エコシステムアーキテクチャを設計する：Plan エージェントを使用して、ツールの境界、トランスポートの選択、セキュリティスコープを整理します

参考資料

• サーバー開発、ツール設計、引数のフラット化、ページネーション、エラー処理
• トランスポートの設定：Stdio、Streamable HTTP、SSE からの移行
• セキュリティ、OAuth 2.1 統合、情報引き出し、機能スコープ、HITL ゲート
• テストと評価：MCP Inspector、単体テスト、コントラクトテスト、CI 統合
• トラブルシューティングガイド、MCP Inspector、よくあるエラー、トランスポートのデバッグ