Skip to content

Tools

Documentation Index

完全なドキュメント索引を取得してください: modelcontextprotocol.io/llms.txt

さらに先へ進む前に、利用可能なすべてのページを把握するために、このファイルを使用してください。

The Model Context Protocol (MCP) は、server が language model から呼び出せる tool を公開することを可能にします。Tool により、model は database への問い合わせ、API 呼び出し、計算の実行など、外部 system とやり取りできます。各 tool は name によって一意に識別され、その schema を説明する metadata を含みます。

User Interaction Model

MCP における Tool は model-controlled になるよう設計されています。つまり、language model が文脈理解とユーザーの prompt に基づいて、自動的に tool を見つけて呼び出せます。

ただし、実装は自身の要件に合う任意のインターフェイスパターンで tool を公開して構いません。プロトコル自体は、特定のユーザーインタラクションモデルを義務付けていません。

trust & safety および security のために、tool invocation を拒否できる人間が常に介在しているべきです (SHOULD)。

アプリケーションは次を行うべきです (SHOULD)。

  • どの tool が AI model に公開されているかを明確に示す UI を提供する
  • tool が呼び出されたときに明確な視覚的インジケータを挿入する
  • 人間が関与していることを保証するため、operation に対する確認 prompt をユーザーに提示する

Capabilities

tool をサポートする server は、tools capability を宣言しなければなりません (MUST)。

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

listChanged は、利用可能な tool の一覧が変更されたときに server が notification を送信するかどうかを示します。

Protocol Messages

Listing Tools

利用可能な tool を見つけるために、client は tools/list request を送信します。この操作は pagination をサポートします。

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        },
        "icons": [
          {
            "src": "https://example.com/weather-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ],
        "execution": {
          "taskSupport": "optional"
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

Calling Tools

tool を呼び出すために、client は tools/call request を送信します。

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}

List Changed Notification

利用可能な tool の一覧が変化したとき、listChanged capability を宣言している server は notification を送信すべきです (SHOULD)。

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

Message Flow

sequenceDiagram participant LLM participant Client participant Server Note over Client,Server: Discovery Client->>Server: tools/list Server-->>Client: List of tools Note over Client,LLM: Tool Selection LLM->>Client: Select tool to use Note over Client,Server: Invocation Client->>Server: tools/call Server-->>Client: Tool result Client->>LLM: Process result Note over Client,Server: Updates Server--)Client: tools/list_changed Client->>Server: tools/list Server-->>Client: Updated tools

Data Types

Tool

tool 定義には次が含まれます。

  • name: tool の一意な識別子
  • title: 表示用の、人が読める任意の tool 名
  • description: 機能を説明する、人が読める説明
  • icons: ユーザーインターフェイス表示用の任意の icon 配列
  • inputSchema: 想定されるパラメータを定義する JSON Schema
    • JSON Schema usage guideline に従う
    • $schema field が存在しない場合は 2020-12 がデフォルト
    • 有効な JSON Schema object でなければならない（null ではない）
    • パラメータを持たない tool では、次のいずれかの有効な方法を使う
      • { "type": "object", "additionalProperties": false } - 推奨: 空 object だけを明示的に受け入れる
      • { "type": "object" } - 任意の object を受け入れる（property を含むものも可）
  • outputSchema: 想定される出力構造を定義する任意の JSON Schema
    • JSON Schema usage guideline に従う
    • $schema field が存在しない場合は 2020-12 がデフォルト
  • annotations: tool の振る舞いを説明する任意の property
  • execution: 実行に関する property を説明する任意の object
    • taskSupport: この tool が task-augmented execution をサポートするかどうかを示す。値は "forbidden"（デフォルト）、"optional"、"required"

trust & safety および security のために、client は、trusted server から来たものでない限り、tool annotation を信頼してはなりません (MUST NOT)。

Tool Names

  • tool 名は、1 文字以上 128 文字以下であるべきです (SHOULD)
  • tool 名は、大文字小文字を区別するものとして扱うべきです (SHOULD)
  • 許可される文字は、ASCII の英大文字・小文字（A-Z, a-z）、数字（0-9）、underscore（_）、hyphen（-）、dot（.）だけであるべきです (SHOULD)
  • tool 名には、space、comma、その他の特殊文字を含めるべきではありません (SHOULD NOT)
  • tool 名は、server 内で一意であるべきです (SHOULD)
  • 有効な tool 名の例:
    • getUser
    • DATA_EXPORT_v2
    • admin.tools.list

Tool Result

tool result には、structured content または unstructured content を含められます。

Unstructured content は result の content field に返され、異なる型の複数 content item を含められます。

すべての content type（text、image、audio、resource link、embedded resource）は、audience、priority、modification time に関する metadata を与える任意の annotation をサポートします。これは、resource や prompt と同じ annotation format です。

Text Content

{
  "type": "text",
  "text": "Tool result text"
}

Image Content

{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png",
  "annotations": {
    "audience": ["user"],
    "priority": 0.9
  }
}

Audio Content

{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

tool は、追加の context や data を提供するために、Resources への link を返しても構いません (MAY)。その場合、tool は、client が subscribe または取得できる URI を返します。

{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

resource link は、通常の resource と同じ Resource annotation をサポートし、client がその使い方を理解する助けになります。

tool から返された resource link が、resources/list request の結果に現れるとは限りません。

Embedded Resources

Resources は、適切な URI scheme を用いて追加の context や data を提供するために埋め込んでも構いません (MAY)。embedded resource を使う server は、resources capability を実装すべきです (SHOULD)。

{
  "type": "resource",
  "resource": {
    "uri": "file:///project/src/main.rs",
    "mimeType": "text/x-rust",
    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
    "annotations": {
      "audience": ["user", "assistant"],
      "priority": 0.7,
      "lastModified": "2025-05-03T14:30:00Z"
    }
  }
}

embedded resource は、通常の resource と同じ Resource annotation をサポートし、client がその使い方を理解する助けになります。

Structured Content

Structured content は、result の structuredContent field に JSON object として返されます。

後方互換性のため、structured content を返す tool は、serialized された JSON を TextContent block として返すべきでもあります (SHOULD)。

Output Schema

tool は、structured result の検証のために output schema を提供しても構いません (MAY)。 output schema が提供される場合:

  • server は、この schema に適合する structured result を提供しなければならない
  • client は、この schema に照らして structured result を検証すべきである (SHOULD)

output schema を持つ tool の例:

{
  "name": "get_weather_data",
  "title": "Weather Data Retriever",
  "description": "Get current weather data for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Temperature in celsius"
      },
      "conditions": {
        "type": "string",
        "description": "Weather conditions description"
      },
      "humidity": {
        "type": "number",
        "description": "Humidity percentage"
      }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

この tool に対する有効な response の例:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
      }
    ],
    "structuredContent": {
      "temperature": 22.5,
      "conditions": "Partly cloudy",
      "humidity": 65
    }
  }
}

output schema を提供することで、client と LLM は structured tool output を理解し、適切に扱いやすくなります。具体的には次の利点があります。

  • response に対する厳密な schema 検証が可能になる
  • programming language とのよりよい統合のために型情報を提供できる
  • client と LLM が返された data を正しく parse して利用するよう導ける
  • documentation や developer experience を改善できる

Schema Examples

デフォルトの 2020-12 schema を使う tool:

{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

明示的な draft-07 schema を使う tool:

{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

パラメータを持たない tool:

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

Error Handling

tool では、2 つの error reporting mechanism が使われます。

  1. Protocol Errors: 次のような問題に対する標準 JSON-RPC error

    • 未知の tool
    • 不正な request（CallToolRequest schema を満たさない request）
    • server error

  2. Tool Execution Errors: isError: true を持つ tool result として報告されるもの

    • API failure
    • input validation error（たとえば日付形式が不正、値が範囲外）
    • business logic error

Tool Execution Errors は、language model が自己修正し、パラメータを調整して再試行するために使える、実行可能なフィードバックを含みます。 Protocol Errors は request 構造自体の問題を示し、model が修正できる可能性は比較的低いです。 client は、自己修正を可能にするため、tool execution error を language model に提供すべきです (SHOULD)。 client は protocol error を language model に提供しても構いませんが、成功する回復につながる可能性は比較的低いです (MAY)。

protocol error の例:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

tool execution error（input validation）の例:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
      }
    ],
    "isError": true
  }
}

Security Considerations

  1. server は次を満たさなければならない

    • すべての tool input を検証する
    • 適切な access control を実装する
    • tool invocation を rate limit する
    • tool output を sanitize する

  2. client は次を行うべきである

    • 機微な operation ではユーザー確認を求める
    • 悪意ある、または偶発的な data exfiltration を避けるため、server を呼ぶ前に tool input をユーザーに見せる
    • LLM に渡す前に tool result を検証する
    • tool call に timeout を実装する
    • 監査目的で tool usage を記録する