mcp-patterns

MCP パターン

Model Context Protocol サーバーの構築、組み合わせ、セキュリティ保護のためのパターンです。2025-11-25 仕様に基づいています。これは、Anthropic、Block、OpenAI が共同設立した Agentic AI Foundation（Linux Foundation）が管理する最新の安定版リリースです。

新しいサーバーをスキャフォールディングしますか？ プロジェクトのセットアップと評価の作成には、Anthropic の mcp-builder スキル（anthropics/skills マーケットプレイスから利用可能：/plugin marketplace add anthropics/skills）を使用してください。このスキルでは、初期セットアップ後のパターン、セキュリティ、高度な機能に焦点を当てています。

Cloudflare にデプロイしますか？ Workers 固有のデプロイパターンについては、building-mcp-server-on-cloudflare スキルを参照してください。

移行するまでは mcp<2 に固定してください。 このスキルの Python スニペットはすべて v1 SDK （from mcp.server.fastmcp import FastMCP）を対象としています。Python SDK の 2.0.0 がリリースされ、pip install mcp は現在これをインストールします。また、上流の README では、移行が完了するまでは要件に <2 の上限を設定するよう記載されています。 2.0 の README には FastMCP が一切登場しないため、これらのスニペットが引き続き適用されると考えず、v1 専用として扱ってください。v1.x は独自のブランチで、重大なバグ修正とセキュリティ修正の提供が継続されます。2026-07-31 確認済み。 移行ガイド：https://py.sdk.modelcontextprotocol.io/migration/

デシジョンツリー — 読むべきルール

What are you building?
│
├── New MCP server
│   ├── Setup & primitives ──────► rules/server-setup.md
│   ├── Transport selection ─────► rules/server-transport.md
│   └── Scaffolding ─────────────► mcp-builder skill (anthropics/skills)
│
├── Authentication & authorization
│   └── OAuth 2.1 + OIDC ───────► rules/auth-oauth21.md
│
├── Advanced server features
│   ├── Tool composition ────────► rules/advanced-composition.md
│   ├── Resource caching ────────► rules/advanced-resources.md
│   ├── Elicitation (user input) ► rules/elicitation.md
│   ├── Sampling (agent loops) ──► rules/sampling-tools.md
│   └── Interactive UI ──────────► rules/apps-ui.md
│
├── Client-side consumption
│   └── Connecting to servers ───► rules/client-patterns.md
│
├── Security hardening
│   ├── Prompt injection defense ► rules/security-injection.md
│   └── Zero-trust & verification ► rules/security-hardening.md
│
├── Testing & debugging
│   └── Inspector + unit tests ──► rules/testing-debugging.md
│
├── Discovery & ecosystem
│   └── Registries & catalogs ──► rules/registry-discovery.md
│
└── Browser-native tools
    └── WebMCP (W3C) ───────────► rules/webmcp-browser.md

クイックリファレンス

カテゴリ	ルール	影響度	主なパターン
サーバー	server-setup.md	高	FastMCP のライフスパン、Tool／Resource／Prompt のプリミティブ
サーバー	server-transport.md	高	CLI には stdio、本番環境には Streamable HTTP
認証	auth-oauth21.md	高	PKCE、RFC 8707 リソースインジケーター、トークン検証
高度な機能	advanced-composition.md	中	パイプライン、並列、分岐によるツールの合成
高度な機能	advanced-resources.md	中	TTL、LRU 追い出し、ライフサイクルを用いたリソースのキャッシュ
高度な機能	elicitation.md	中	サーバーからユーザーに開始する構造化入力
高度な機能	sampling-tools.md	中	ツール呼び出しを伴うサーバー側エージェントループ
高度な機能	apps-ui.md	中	MCP Apps + @mcp-ui/* SDK によるインタラクティブ UI
クライアント	client-patterns.md	中	TypeScript／Python の MCP クライアント接続パターン
セキュリティ	security-injection.md	高	説明のサニタイズ、エンコーディングの正規化
セキュリティ	security-hardening.md	高	ゼロトラストの許可リスト、ハッシュ検証、ラグプル検出
品質	testing-debugging.md	中	MCP Inspector、ユニットテスト、トランスポートのデバッグ
エコシステム	registry-discovery.md	低	公式レジストリ API、サーバーメタデータ
エコシステム	webmcp-browser.md	低	W3C のブラウザー組み込みエージェントツール（補完的）

合計：6 カテゴリ、14 ルール

主な判断事項

判断事項	推奨事項
トランスポート	CLI／デスクトップには stdio、本番環境には Streamable HTTP（SSE は非推奨）
言語	本番環境には TypeScript（SDK のサポートが優れ、型安全性が高い）
認証	PKCE（S256）+ RFC 8707 リソースインジケーターを用いた OAuth 2.1
サーバーのライフサイクル	リソース管理には必ず FastMCP のライフスパンを使用する
エラー処理	エラーをテキストコンテンツとして返す（Claude が解釈して再試行できます）
ツールの合成	順次処理にはパイプライン、並列処理には asyncio.gather
リソースのキャッシュ	メモリ上限を設け、TTL + LRU 追い出しを使用する
ツールの信頼モデル	ゼロトラスト：明示的な許可リスト + ハッシュ検証
ユーザー入力	実行時の入力には Elicitation を使用し、Elicitation で個人情報を決して要求しない
インタラクティブ UI	@mcp-ui/* SDK を用いた MCP Apps を使用し、すべての iframe をサンドボックス化する
トークンの取り扱い	クライアントのトークンを下流サービスに決して受け渡さない
大きな結果	切り詰めると意味が失われる結果には _meta["anthropic/maxResultSizeChars"] アノテーションを使用する（最大 500K）（CC 2.1.91）

仕様とガバナンス

• プロトコル：Model Context Protocol、仕様バージョン 2025-11-25（最新の安定版）
• ガバナンス：Agentic AI Foundation（Linux Foundation、2025年12月）
• プラチナメンバー：AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAI
• 採用状況：10,000 以上のサーバー。Claude、Cursor、Copilot、Gemini、ChatGPT、VS Code
• 仕様の URL：https://modelcontextprotocol.io/specification/2025-11-25
• 2026年のモデル：ワーキンググループとインタレストグループが、プロトコルを進化させるための主な手段になりました（マイルストーンベースのリリースは廃止）。エンタープライズ対応は、仕様のコアを変更するのではなく、拡張機能として提供されます。

機能の成熟度

機能	仕様バージョン	ステータス
ツール、リソース、プロンプト	2024-11-05	安定
Streamable HTTP トランスポート	2025-03-26	安定（SSE を置き換え）
OAuth 2.1 + Elicitation（フォーム）	2025-06-18	安定
ツール呼び出しを伴うサンプリング	2025-11-25	安定
Elicitation URL モード	2025-11-25	安定
MCP Apps（UI 拡張機能）	2026-01-26	拡張機能（ext-apps）
WebMCP（ブラウザー標準）	2026-02-14	W3C コミュニティー草案

SDK の状況（2026-Q2）

パッケージ	内容	使用する場合
mcp (PyPI) >=1.27	公式 Python SDK — FastMCP ヘルパー、トランスポートアダプター、Inspector を含みます	新しい Python サーバー。このパッケージが標準です。
@modelcontextprotocol/sdk (npm) >=1.29	公式 TypeScript SDK	新しい TS サーバー
fastmcp (PyPI)	jlowin によるスタンドアロンのフォーク — mcp より前から存在し、API 互換ですが、ライフスパンやミドルウェアの扱いは異なります	既存プロジェクトがこのパッケージに固定されている場合に使用します。新しいプロジェクトでは mcp を優先してください。

fastmcp フォークと mcp.server.fastmcp モジュールは同じパッケージではありません。インポートと pyproject.toml のエントリーが一致しないと、スタックトレースが非常に分かりにくくなります。

Claude Code によるデバッグ

サーバーの接続設定を調査するときは、Claude Code に --mcp-debug を渡してください。デフォルトのロガーでは記録されない、生の JSON-RPC フレーム、ハンドシェイクの失敗、ツール登録イベントが表示されます。

claude --mcp-debug "query the local test server"
# or per-session:
export CLAUDE_MCP_DEBUG=1

MCP Inspector（npx @modelcontextprotocol/inspector <cmd>）と併用してください。Inspector ではクライアント側のフレームを確認でき、--mcp-debug では Claude が実際に受け取った内容を確認できます。

CC 2.1.128 — 再接続時のツール要約：セッション中にサーバーが再接続すると、再通知されたツールは行ごとに列挙されず、mcp__<server>__* (N tools re-registered) として要約されます。ツール一覧の正確な情報源として 初回接続 イベントを使用し、再接続時の要約は差分としてのみ扱ってください。どちらの形式にも対応する grep の例については、references/mcp-audit-runbook.md を参照してください。

CC 2.1.133 — MCP OAuth が HTTP(S)_PROXY / NO_PROXY / mTLS に対応：MCP OAuth の全フロー（検出、動的クライアント登録、トークン交換、トークン更新）が、標準のプロキシおよびクライアント証明書の環境変数をフロー全体で尊重するようになりました。企業プロキシの背後にあるエンタープライズ環境でも、OAuth 固有の回避策は不要になりました。MCP トランスポートの経路設定にすでに使用している HTTPS_PROXY / NO_PROXY / NODE_EXTRA_CA_CERTS の設定で、認証の経路も設定されます。環境変数の例については、configure/references/cc-version-settings.md（CC 2.1.133 のセクション）を参照してください。関連するデプロイスキル building-mcp-server-on-cloudflare では、このバージョン以降、「プロキシ対応 OAuth には手動処理が必要」という注意書きを削除できます。

CC 2.1.169 — 管理対象 MCP ポリシーをすべてのケースで適用：エンタープライズの allowedMcpServers / deniedMcpServers が、再接続時、IDE 形式の設定、インストール後の最初のセッションにおける --mcp-config サーバー、リモート設定の読み込み前にも適用されるようになりました（以前は、これら4つの経路すべてで適用がスキップされていました）。リモート設定のない組織では、コールドスタートも高速化されます。2.1.169 への更新後、以前は動作していたサーバーが接続できなくなった場合は、サーバーのデバッグ前に管理対象ポリシーを確認してください。

CC 2.1.163 — stdio サーバーに CLAUDE_CODE_SESSION_ID を設定：--resume を使用すると、stdio MCP サーバーにも、フックや Bash がすでに受け取っているのと同じ CLAUDE_CODE_SESSION_ID 環境変数が渡されます。サーバー内でこの値を読み取り、再開したセッション間でログやテレメトリーを関連付けてください。独自のセッションキーを生成する必要はありません。ただし、この値をキーとして認証トークンを保存してはいけません（「よくある間違い」#7 を参照）。

例

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
async def search(query: str) -> str:
    """Search documents. Returns matching results."""
    results = await db.search(query)
    return "\n".join(r.title for r in results[:10])

よくある間違い

1. ライフサイクル管理がない（シャットダウン時に接続やリソースがリークする）
2. ツール引数の入力検証がない
3. ツールの出力に秘密情報（API キー、認証情報）を返す
   • CC 2.1.161 では CLI 層でこの問題が軽減されます。claude mcp list/get/add は ${VAR} 参照を展開しなくなり、ターミナル出力では認証情報ヘッダーと URL 内の秘密情報がマスキングされます。ただし、サーバーコードからツールの 結果 に秘密情報を返してはいけません。/mcp でも、サインインしたことのないコネクターは「未使用のコネクターを表示」行にまとめられます。
   • CC 2.1.186 では、OAuth 対応サーバー（HTTP/SSE/コネクター）向けに claude mcp login <name> / claude mcp logout <name> が追加されました。ブラウザーを開かずに認証 URL を表示するには --no-browser を渡します。これは SSH／ヘッドレス／リモートセッションでサポートされる方法です（プロンプトが表示されたら、リダイレクト URL を貼り付けてください）。そのため、対話型認証によって自動セットアップが妨げられることはありません。
4. _meta アノテーションのない、サイズ上限のないレスポンス。意図的に大きな結果（DB スキーマ、API 仕様）を返す場合は、_meta["anthropic/maxResultSizeChars"] を使用して宣言し、クライアントやフックによる切り詰めを防いでください
5. サニタイズせずにツールの説明を信頼する（インジェクションのリスク）
6. ツール呼び出し時にハッシュを検証しない（ラグプルの脆弱性）
7. 認証トークンをセッション ID に保存する（認証情報の漏えい）
8. 非同期サーバーで同期コードをブロックする（asyncio.to_thread() を使用してください）
9. Streamable HTTP ではなく SSE トランスポートを使用する（2025年3月以降、非推奨）
10. クライアントのトークンを下流サービスにそのまま渡す（混乱した代理人の問題）

エコシステム

リソース	用途
mcp-builder skill (anthropics/skills)	新しい MCP サーバーのひな形を作成し、評価を実施します
building-mcp-server-on-cloudflare skill	MCP サーバーを Cloudflare Workers にデプロイします
@mcp-ui/* packages (npm)	MCP Apps UI 標準を実装します
MCP Registry	サーバーを検索します：https://registry.modelcontextprotocol.io/
MCP Inspector	サーバーを対話形式でデバッグおよびテストします

関連スキル

• ork:llm-integration — LLM の関数呼び出しパターン
• ork:security-patterns — 一般的な入力のサニタイズと多層セキュリティ
• ork:api-design — REST/GraphQL API の設計パターン