0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Hurry_Fox(Hurry Fox)

MCP 仕様重要事項チートシート

0
Posted at

MCP 仕様重要事項チートシート

1. アーキテクチャ

3層構造

  • Host: クライアントを管理、ユーザー認可を制御
  • Client: サーバーへの接続、メッセージルーティング
  • Server: ツール・リソース・プロンプトを提供

トランスポート

  • STDIO: ローカルサーバー（標準入出力）
  • HTTP+SSE: リモートサーバー（Server-Sent Events）

2. プリミティブ（核心機能）

Tools（ツール）

AIが実行できる機能

  • tools/list - 一覧取得
  • tools/call - 実行
  • inputSchema で引数定義（JSON Schema）

Resources（リソース）

AIがアクセスするデータ

  • resources/list - 一覧
  • resources/read - 読み取り
  • resources/subscribe - 変更購読
  • resources/templates/list - 動的URIパターン

Prompts（プロンプト）

再利用可能なテンプレート

  • prompts/list - 一覧
  • prompts/get - 取得（引数で展開）

3. プロトコル基礎

JSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {}
}

必須フロー

  1. initialize - 機能交換
  2. initialized 通知 - 準備完了
  3. 通常のリクエスト/レスポンス

プロトコルバージョン

2025-11-25（Initialize時に指定）

4. クライアント機能

Sampling

サーバーがLLMを呼び出す

  • sampling/createMessage
  • モデル選択ヒント、優先度指定可能

Roots

サーバーが動作範囲を問い合わせ

  • roots/list - 許可されたディレクトリ等

Logging

サーバーがログを送信

  • notifications/message
  • レベル: debug, info, warning, error等

5. ユーティリティ

Progress（進捗通知）

長時間操作の進捗報告

  • _meta.progressToken で識別
  • notifications/progress

Cancellation（キャンセル）

操作中断

  • notifications/cancelled

Completion（補完）

引数の入力候補提供

  • completion/complete

Pagination

大量データの分割取得

  • nextCursor でページング

6. Tasks（実験的）

長時間実行タスク

  • _meta.task.ttl でタスク化
  • tasks/get で状態確認
  • ステータス: pending, running, completed, failed

7. 認証・認可（OAuth 2.0）

フロー

  1. 401受信 → Protected Resource Metadata
  2. 認証サーバー発見（OIDC Discovery）
  3. Dynamic Client Registration
  4. Authorization Code Flow
  5. アクセストークン取得

トークン検証（必須）

  • aud - トークンの宛先
  • scope - 必要なスコープ
  • exp - 有効期限
  • iss - 発行元
  • active - 状態（Token Introspection）

8. セキュリティ重要事項

Token Passthrough（禁止）

❌ クライアントのトークンを別APIに転送禁止
✅ 必ず aud 検証、自分の資格情報を使用

Confused Deputy対策

  • クライアントごとの同意画面必須
  • state パラメータ検証
  • redirect_uri 厳格チェック
  • 同意Cookieは承認後に設定

Session Hijacking対策

  • セッションIDを認証に使用しない
  • ユーザーIDとバインド
  • 安全なランダムID生成

SSRF対策

  • プライベートIP範囲ブロック
    • 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • 127.0.0.0/8, 169.254.0.0/16
  • HTTPS強制

9. エラーコード

JSON-RPC標準

  • -32700: Parse error
  • -32600: Invalid Request
  • -32601: Method not found
  • -32602: Invalid params
  • -32603: Internal error

MCP拡張

  • -32000: Tool execution error
  • -32001: Resource not found
  • -32002: Prompt not found

10. ベストプラクティス

サーバー実装

  • ツール名は snake_case
  • 明確な説明（AIが理解可能に）
  • エラーは isError: true + 詳細
  • 長時間操作はProgress実装

クライアント実装

  • initialize 後に initialized 必須
  • タイムアウト設定（推奨30秒）
  • エラーハンドリング実装

セキュリティ

  • すべての入力を検証
  • トークン検証必須
  • 最小権限の原則
  • 監査ログ実装

11. パフォーマンス推奨値

タイムアウト

  • Initialize: 5秒
  • ツール実行: 30秒
  • リソース取得: 10秒

レート制限

  • ツール呼び出し: 10回/秒
  • リソース購読: 100件/ユーザー
  • Progress通知: 1回/秒

12. 重要なメッセージ形式

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {"tools": {}, "resources": {}, "prompts": {}},
    "clientInfo": {"name": "client", "version": "1.0.0"}
  }
}

Tools Call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {"arg1": "value1"}
  }
}

Resources Read

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {"uri": "file:///path/to/file.txt"}
}

Progress Notification

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "token123",
    "progress": 50,
    "total": 100
  }
}

13. 通知（Notifications）

サーバー → クライアント

  • notifications/tools/list_changed - ツールリスト変更
  • notifications/resources/list_changed - リソースリスト変更
  • notifications/resources/updated - リソース更新
  • notifications/prompts/list_changed - プロンプトリスト変更
  • notifications/progress - 進捗
  • notifications/message - ログメッセージ

クライアント → サーバー

  • notifications/initialized - 初期化完了
  • notifications/cancelled - キャンセル
  • notifications/roots/list_changed - ルート変更

14. Extensions（拡張機能）

標準拡張

  • io.modelcontextprotocol/oauth-client-credentials
  • io.modelcontextprotocol/enterprise-managed-authorization

MCP Apps

  • text/html;profile=mcp-app
  • ブラウザベースUIを提供

15. URIスキーム

標準的な使用例

  • file:///absolute/path/to/file.txt
  • db://table_name/record_id
  • https://api.example.com/resource
  • custom://scheme/path

Resource Templates

  • file:///{path} - 任意パス
  • db://{table}/{id} - 動的テーブル/ID

16. Capabilities（機能宣言）

サーバー側

{
  "capabilities": {
    "tools": {"listChanged": true},
    "resources": {"subscribe": true, "listChanged": true},
    "prompts": {"listChanged": true},
    "logging": {}
  }
}

クライアント側

{
  "capabilities": {
    "roots": {"listChanged": true},
    "sampling": {},
    "experimental": {}
  }
}

17. 設計原則

ステートレス

  • 各リクエストは独立
  • 最小限の状態のみ保持

セキュリティ第一

  • 入力検証必須
  • トークン検証必須
  • 最小権限
  • 監査ログ

拡張性

  • プリミティブの組み合わせ
  • カスタムURI
  • Extensions機能

18. デバッグのコツ

よくある問題

  • Initialize未実行
  • JSON-RPC形式エラー
  • プロトコルバージョン不一致
  • トークン検証ミス

ログ確認ポイント

  • JSON-RPCメッセージ全体
  • エラースタックトレース
  • タイムスタンプ
  • リクエストID

まとめ：MCPの本質

3つのプリミティブでAIと外部世界を接続

  • Tools: 実行
  • Resources: データ
  • Prompts: テンプレート

JSON-RPC 2.0で標準化された通信

OAuth 2.0でセキュアな認証

拡張性のある設計で将来に対応

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?