T-CREATOR

MCP サーバー クイックリファレンス：Tool 宣言・リクエスト／レスポンス・エラーコード・ヘッダー早見表

MCP サーバー クイックリファレンス：Tool 宣言・リクエスト／レスポンス・エラーコード・ヘッダー早見表

MCP サーバーを実装する際、最も頻繁に参照するのが Tool 宣言の仕様、JSON-RPC のリクエスト/レスポンス形式、エラーコード、そして HTTP ヘッダーです。本記事では、これらの情報を素早く確認できるクイックリファレンスとして、実装時に役立つ具体例とともにご紹介します。

早見表

Tool 宣言仕様

#項目必須説明例
1name★ツールの一意識別子"get_weather"
2description★機能の人間可読な説明"Perform basic math operations"
3inputSchema★JSON Schema 形式のパラメータ定義{"type": "object", "properties": {...}}
4title-表示用名称"Weather Information Tool"
5outputSchema-出力構造の定義{"type": "object", "properties": {...}}

主要メソッド：リクエスト／レスポンス

#メソッド方向必須パラメータレスポンス内容
1initializeClient → ServerprotocolVersion, capabilities, clientInfoprotocolVersion, capabilities, serverInfo
2initializedClient → Server-- (通知)
3tools/listClient → Servercursor (オプション)tools 配列（name, description, inputSchema）
4tools/callClient → Servername, argumentscontent 配列、isError

JSON-RPC エラーコード

#コード名称意味
1-32700Parse ErrorJSON 構文エラー
2-32600Invalid Requestプロトコル要件違反
3-32601Method Not Found未対応メソッド
4-32602Invalid Paramsパラメータ検証失敗
5-32603Internal Errorサーバー実装内の問題
6-32002Resource Errorリソース不在・アクセス不可
7-32000 ～-32099Server Error実装固有エラー

HTTP ヘッダー仕様

#ヘッダー名必須説明例
1Accept★サポートするコンテンツタイプapplication​/​json, text​/​event-stream
2MCP-Protocol-Version★交渉済みプロトコル版2025-03-26
3Mcp-Session-Id★セッション ID（初期化後）sess-abc123
4Last-Event-ID-再接続時の最終イベント IDevent-456
5Content-Type★レスポンス形式application​/​json / text​/​event-stream

HTTP ステータスコード

#コード状況説明
1202 Accepted通知/レスポンス受理本文なし
2400 Bad Request不正リクエスト無効 JSON、無効プロトコル版
3404 Not Foundセッション終了セッションが存在しない
4405 Method Not Allowed非対応操作SSE 非対応など

背景

MCP（Model Context Protocol）とは

Model Context Protocol（MCP）は、LLM（大規模言語モデル）アプリケーションに対してコンテキストを提供するための標準化されたオープンプロトコルです。

2025 年 3 月現在、最新のプロトコル版は 2025-03-26 であり、Streamable HTTP transport が標準的なトランスポート方式として採用されています。

MCP の通信基盤

MCP は JSON-RPC 2.0 仕様に準拠した通信プロトコルを採用しています。

クライアントとサーバー間のすべてのやり取りは、JSON-RPC 形式のメッセージとして構造化されており、リクエスト、レスポンス、通知の 3 つの基本タイプで構成されます。

以下の図は、MCP におけるクライアントとサーバー間の基本的な通信フローを示しています。

mermaidsequenceDiagram
    participant C as Client<br/>(Claude等)
    participant S as MCP Server

    C->>S: initialize request
    S->>C: initialize response
    C->>S: initialized notification
    C->>S: tools/list request
    S->>C: tools/list response
    C->>S: tools/call request
    S->>C: tools/call response

図で示した通り、初期化フェーズを経て、クライアントはツール一覧を取得し、必要なツールを呼び出す流れとなります。

なぜクイックリファレンスが必要か

MCP サーバーの開発では、以下のような情報を何度も確認する必要があります。

  • Tool 宣言時のスキーマ定義方法
  • リクエスト/レスポンスの正しい形式
  • エラー発生時の適切なエラーコード
  • 必須 HTTP ヘッダーの種類と値

公式仕様書は詳細ですが、実装中に素早く確認したい場合には情報が分散していて不便です。そこで本記事では、これらの情報を 1 つの記事にまとめ、開発効率を向上させることを目的としています。

課題

仕様理解の複雑さ

MCP サーバーを実装する際、開発者は以下のような課題に直面します。

ツール定義の正確性

ツールを定義する際、JSON Schema の形式を正確に理解し、LLM が適切に解釈できる構造で記述する必要があります。

特に inputSchema の定義が不正確だと、クライアント側でパラメータの検証が失敗し、ツールが正しく呼び出されません。

エラーハンドリングの統一性

MCP では、プロトコルレベルのエラーとアプリケーションレベルのエラーを区別する必要があります。

JSON-RPC エラーコードを適切に使い分けることで、クライアント側がエラーの原因を正確に特定できるようになります。

HTTP トランスポートの理解

Streamable HTTP transport では、複数の HTTP ヘッダーが必須となり、それぞれの役割を理解する必要があります。

特に MCP-Protocol-Version や Mcp-Session-Id の扱いを誤ると、通信自体が確立できません。

以下の図は、MCP サーバー実装における主な課題領域を示しています。

mermaidflowchart TD
    challenge["MCP実装の課題"]
    challenge --> tool_def["Tool定義の複雑さ"]
    challenge --> error_handling["エラーハンドリング"]
    challenge --> http_transport["HTTPトランスポート"]

    tool_def --> schema["JSON Schema理解"]
    tool_def --> validation["パラメータ検証"]

    error_handling --> protocol_error["プロトコルエラー"]
    error_handling --> app_error["アプリケーションエラー"]

    http_transport --> headers["必須ヘッダー"]
    http_transport --> session["セッション管理"]

これらの課題を解決するには、各要素の仕様を正確に把握し、実装時に素早く参照できる資料が必要です。

解決策

クイックリファレンスの活用

本記事で提供する早見表と具体例を活用することで、以下の解決策が実現できます。

Tool 宣言の標準化

Tool 定義に必要な要素を表形式でまとめることで、必須項目とオプション項目を一目で確認できます。

これにより、ツール定義の漏れや誤りを防ぎ、一貫性のある実装が可能になります。

エラーコードの体系的理解

JSON-RPC エラーコードを一覧化することで、エラー発生時に適切なコードを即座に選択できます。

エラーの意味と使用場面を明確にすることで、デバッグ効率も向上します。

HTTP ヘッダーのチェックリスト化

必須ヘッダーとオプションヘッダーを表形式で整理することで、実装漏れを防ぎます。

各ヘッダーの役割と具体例を示すことで、正しい値を設定できるようになります。

以下の図は、クイックリファレンスを使った開発フローを示しています。

mermaidflowchart LR
    start["開発開始"] --> ref["早見表参照"]
    ref --> impl["実装"]
    impl --> test["テスト"]
    test --> error{エラー?}
    error -->|Yes| ref
    error -->|No| done["完成"]

早見表を開発サイクルに組み込むことで、実装とデバッグのスピードが大幅に向上します。

具体例

Tool 宣言の実装例

ここでは、天気情報を取得するツールを例に、Tool 宣言の具体的な実装方法を解説します。

基本的な Tool 定義

まず、ツール名と説明を定義します。

typescriptconst weatherTool = {
  name: 'get_weather',
  description: '指定された地域の現在の天気情報を取得します',
};

ツール名は一意である必要があり、説明は LLM がツールの用途を理解するために重要です。

inputSchema の定義

次に、JSON Schema を使ってパラメータを定義します。

typescriptconst weatherTool = {
  name: 'get_weather',
  description: '指定された地域の現在の天気情報を取得します',
  inputSchema: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: '天気情報を取得する地域名',
      },
      units: {
        type: 'string',
        enum: ['celsius', 'fahrenheit'],
        description: '温度の単位',
      },
    },
    required: ['location'],
  },
};

properties でパラメータを定義し、required で必須パラメータを指定します。

outputSchema の追加（オプション）

出力の構造を明示的に定義することもできます。

typescriptconst weatherTool = {
  name: 'get_weather',
  description: '指定された地域の現在の天気情報を取得します',
  inputSchema: {
    // ...前述のスキーマ
  },
  outputSchema: {
    type: 'object',
    properties: {
      temperature: {
        type: 'number',
        description: '現在の気温',
      },
      conditions: {
        type: 'string',
        description: '天気の状態',
      },
    },
  },
};

outputSchema を定義することで、クライアント側が戻り値の構造を事前に理解できます。

リクエスト／レスポンスの実装例

initialize リクエスト

クライアントがサーバーに接続する際の初期化リクエストです。

json{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "roots": {
        "listChanged": true
      }
    },
    "clientInfo": {
      "name": "ClaudeClient",
      "version": "1.0.0"
    }
  }
}

protocolVersion は使用する MCP バージョンを指定し、capabilities はクライアントの機能を宣言します。

initialize レスポンス

サーバーからの初期化レスポンスです。

json{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "WeatherServer",
      "version": "1.0.0"
    }
  }
}

サーバーは自身の機能（この例ではツール機能）を capabilities で宣言します。

tools/list リクエスト

利用可能なツール一覧を取得するリクエストです。

json{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

パラメータは基本的に不要ですが、ページネーションが必要な場合は cursor を指定します。

tools/list レスポンス

サーバーが提供するツールの一覧を返します。

json{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "指定された地域の現在の天気情報を取得します",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "天気情報を取得する地域名"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

各ツールには name、description、inputSchema が含まれます。

tools/call リクエスト

実際にツールを実行するリクエストです。

json{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Tokyo"
    }
  }
}

name でツールを指定し、arguments でパラメータを渡します。

tools/call レスポンス（成功時）

ツール実行が成功した場合のレスポンスです。

json{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "東京の現在の天気:\n気温: 22°C\n天候: 晴れ"
      }
    ],
    "isError": false
  }
}

content 配列に結果が格納され、isError は処理の成功/失敗を示します。

tools/call レスポンス（エラー時）

アプリケーションレベルのエラーが発生した場合です。

json{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: 指定された地域が見つかりませんでした"
      }
    ],
    "isError": true
  }
}

isError: true を設定し、エラー内容を content に含めます。

エラーレスポンスの実装例

Method Not Found エラー（-32601）

存在しないメソッドが呼ばれた場合のエラーです。

json{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "method": "tools/unknown"
    }
  }
}

エラーコード -32601 は未対応メソッドを示し、data に追加情報を含められます。

Invalid Params エラー（-32602）

パラメータ検証が失敗した場合のエラーです。

json{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "reason": "Required parameter 'location' is missing"
    }
  }
}

エラーコード -32602 はパラメータ不正を示し、具体的な理由を data に記載します。

Parse Error エラー（-32700）

JSON 構文エラーが発生した場合です。

json{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "data": {
      "position": 45,
      "character": "}"
    }
  }
}

JSON 自体がパースできない場合、id は null になります。

HTTP ヘッダーの実装例

クライアントからの POST リクエスト

ツール呼び出し時の HTTP ヘッダー例です。

httpPOST /mcp HTTP/1.1
Host: example.com
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-03-26
Mcp-Session-Id: sess-abc123
Content-Type: application/json
Content-Length: 156

{実際のJSON-RPCリクエスト}

Accept ヘッダーには両方のコンテンツタイプを指定し、MCP-Protocol-Version は必須です。

サーバーからのレスポンス（JSON）

通常の JSON 形式でのレスポンスです。

httpHTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: sess-abc123

{実際のJSON-RPCレスポンス}

単一の JSON-RPC レスポンスを返す場合は Content-Type: application​/​json を使用します。

サーバーからのレスポンス（SSE）

Server-Sent Events 形式でのレスポンスです。

httpHTTP/1.1 200 OK
Content-Type: text/event-stream
Mcp-Session-Id: sess-abc123

data: {JSON-RPCレスポンス}

複数のメッセージをストリーミングする場合は Content-Type: text​/​event-stream を使用します。

エラーレスポンス（400 Bad Request）

プロトコルバージョンが不正な場合です。

httpHTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "received": "2024-01-01",
      "supported": ["2025-03-26"]
    }
  }
}

HTTP ステータスコード 400 と共に、JSON-RPC エラーを返します。

以下の図は、正常な HTTP 通信フローを示しています。

mermaidsequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: POST /mcp<br/>Accept: application/json, text/event-stream<br/>MCP-Protocol-Version: 2025-03-26
    S->>C: 200 OK<br/>Content-Type: application/json<br/>Mcp-Session-Id: sess-abc123

    C->>S: POST /mcp<br/>Mcp-Session-Id: sess-abc123<br/>{tools/call request}
    S->>C: 200 OK<br/>{tools/call response}

正常な通信では、セッション ID が初期化後のリクエストで引き継がれることが重要です。

エラーハンドリングのベストプラクティス

プロトコルレベルエラーとアプリケーションレベルエラーの使い分け

プロトコルレベルのエラーは、JSON-RPC エラーとして返します。

typescript// プロトコルレベルエラー（JSON-RPCエラー）
if (!request.method) {
  return {
    jsonrpc: '2.0',
    id: request.id,
    error: {
      code: -32600,
      message: 'Invalid Request',
    },
  };
}

JSON-RPC 自体の問題（メソッド不在、パラメータ不正など）はこの方法で処理します。

アプリケーションレベルのエラーは、isError: true で返します。

typescript// アプリケーションレベルエラー（tools/callレスポンス内）
return {
  jsonrpc: '2.0',
  id: request.id,
  result: {
    content: [
      {
        type: 'text',
        text: 'Error: データベース接続エラー',
      },
    ],
    isError: true,
  },
};

ツール実行中の業務ロジックエラーは isError フラグで表現します。

エラーメッセージの検索最適化

エラーメッセージには具体的なエラーコードとキーワードを含めます。

typescript// 検索しやすいエラーメッセージ
const error = {
  code: -32602,
  message:
    "Invalid Params: Required parameter 'location' is missing",
  data: {
    errorCode: 'MISSING_REQUIRED_PARAM',
    parameterName: 'location',
    receivedParams: Object.keys(params),
  },
};

エラーコード（MISSING_REQUIRED_PARAM）やパラメータ名を明記することで、検索性が向上します。

まとめ

本記事では、MCP サーバー開発で頻繁に参照する 4 つの重要要素について、早見表と具体例を用いて解説しました。

Tool 宣言のポイント

ツール定義には name、description、inputSchema が必須であり、JSON Schema を使って正確にパラメータを定義することが重要です。

オプションとして outputSchema を追加することで、クライアント側の型安全性を高められます。

リクエスト／レスポンスの標準形式

MCP では JSON-RPC 2.0 形式を採用しており、jsonrpc、id、method、params の構造を守る必要があります。

特に initialize メソッドでのプロトコルバージョン交渉は、通信確立の基盤となります。

エラーコードの適切な使用

JSON-RPC エラーコード（-32700 ～-32000）はプロトコルレベルのエラーに使用し、アプリケーションレベルのエラーは isError フラグで表現します。

エラーメッセージには具体的な情報を含め、デバッグと検索の効率を高めることが推奨されます。

HTTP ヘッダーの必須要件

Streamable HTTP transport では、Accept、MCP-Protocol-Version、Mcp-Session-Id が主要なヘッダーです。

これらを正しく設定することで、安定した HTTP 通信が実現できます。

本記事の早見表を手元に置いておくことで、MCP サーバー開発の効率が大幅に向上するでしょう。実装時の参照資料として、ぜひご活用ください。

関連リンク

MCP サーバーの記事Mcp Server

もっと見る

記事Article

もっと見る

ブログBlog

もっと見る

書籍レビューReview

もっと見る