Model Context Protocol

https://modelcontextprotocol.io/specification/2025-06-18
Admin
Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM...
Tokens:49,368
Snippets:419
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Model Hints Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/sampling

Example of model hints with capability priorities. Hints are substrings matched flexibly, evaluated in order, and are advisory.

```json
{
  "hints": [
    { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
    { "name": "claude" } // Fall back to any Claude model
  ],
  "costPriority": 0.3, // Cost is less important
  "speedPriority": 0.8, // Speed is very important
  "intelligencePriority": 0.5 // Moderate capability needs
}
```

--------------------------------

### String Schema Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

String schema example for elicitation. Supported formats are email, uri, date, and date-time.

```json
{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "minLength": 3,
  "maxLength": 50,
  "format": "email" // Supported: "email", "uri", "date", "date-time"
}
```

--------------------------------

### Resource with Annotations Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Example resource definition with annotations, including audience, priority, and lastModified. Clients can use these annotations to filter resources, prioritize context inclusion, and display or sort by modification time.

```json
{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "title": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}
```

--------------------------------

### Example HTTP request with Bearer token

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization

Example HTTP GET request to an MCP server, including the Authorization header with a Bearer token. This demonstrates the required format for resource requests.

```http
GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

```

--------------------------------

### Define project directory root

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/roots

Example root definition for a project directory. The uri must be a file:// URI and name is optional.

```json
{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}
```

--------------------------------

### Define multiple repository roots

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/roots

Example list of roots for multiple repositories.

```json
[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]
```

--------------------------------

### Enum Schema Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

Enum schema example for elicitation. Uses enum and enumNames to provide display names for options.

```json
{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "enum": ["option1", "option2", "option3"],
  "enumNames": ["Option 1", "Option 2", "Option 3"]
}
```

--------------------------------

### Declare resources capability with both optional features

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Servers supporting resources MUST declare the 'resources' capability. This example enables both 'subscribe' and 'listChanged'.

```json
{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}
```

--------------------------------

### Binary Resource Content Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Shows the JSON structure for a binary resource, including the uri, mimeType, and blob fields. Use this when a resource contains binary data such as images.

```json
{
  "uri": "file:///example.png",
  "mimeType": "image/png",
  "blob": "base64-encoded-data"
}
```

--------------------------------

### Boolean Schema Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

Boolean schema example for elicitation. Includes a default value of false.

```json
{
  "type": "boolean",
  "title": "Display Name",
  "description": "Description text",
  "default": false
}
```

--------------------------------

### Tool Execution Error Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Example of a tool execution error reported in a tool result with isError set to true.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to fetch weather data: API rate limit exceeded"
      }
    ],
    "isError": true
  }
}
```

--------------------------------

### Text Resource Content Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Shows the JSON structure for a text resource, including the uri, mimeType, and text fields. Use this when a resource contains plain text content.

```json
{
  "uri": "file:///example.txt",
  "mimeType": "text/plain",
  "text": "Resource content"
}
```

--------------------------------

### Number Schema Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

Number schema example for elicitation. The type can be "number" or "integer".

```json
{
  "type": "number", // or "integer"
  "title": "Display Name",
  "description": "Description text",
  "minimum": 0,
  "maximum": 100
}
```

--------------------------------

### requestedSchema Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

Example of the requestedSchema field that servers use to define the expected response structure. It is limited to flat objects with primitive properties only.

```json
"requestedSchema": {
  "type": "object",
  "properties": {
    "propertyName": {
      "type": "string",
      "title": "Display Name",
      "description": "Description of the property"
    },
    "anotherProperty": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    }
  },
  "required": ["propertyName"]
}
```

--------------------------------

### Example initialization error response

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

JSON-RPC error response for an unsupported protocol version. The error code is -32602, and the data field includes the supported and requested protocol versions.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2024-11-05"],
      "requested": "1.0.0"
    }
  }
}
```

--------------------------------

### Pagination Request Format

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination

Example JSON-RPC request that continues pagination by including the cursor received from a previous response.

```json
{
  "jsonrpc": "2.0",
  "id": "124",
  "method": "resources/list",
  "params": {
    "cursor": "eyJwYWdlIjogMn0="
  }
}
```

--------------------------------

### Elicitation response JSON-RPC example

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation

Shows the JSON-RPC response structure for elicitation actions. The action field can be "accept", "decline", or "cancel". For "decline" and "cancel", the content field is typically omitted.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept", // or "decline" or "cancel"
    "content": {
      "propertyName": "value",
      "anotherProperty": 42
    }
  }
}
```

--------------------------------

### initialize

Source: https://modelcontextprotocol.io/specification/2025-06-18/schema

The initialize request is sent from the client to the server when it first connects, asking it to begin initialization. The server responds with an InitializeResult containing the protocol version, server capabilities, server info, and optional instructions.

```APIDOC
## initialize

### Description
This request is sent from the client to the server when it first connects, asking it to begin initialization.

### Method
initialize

### Request
#### Request Body
- **method** (string) - Required - Must be "initialize".
- **params** (object) - Required - Contains protocolVersion, capabilities, and clientInfo.
  - **protocolVersion** (string) - Required - The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.
  - **capabilities** (ClientCapabilities) - Required - Capabilities a client may support.
  - **clientInfo** (Implementation) - Required - Describes the name and version of an MCP implementation.

#### Request Example
```json
{
  "method": "initialize",
  "params": {
    "protocolVersion": "string",
    "capabilities": {},
    "clientInfo": {
      "name": "string",
      "version": "string"
    }
  }
}
```

### Response
#### Success Response
- **protocolVersion** (string) - Required - The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.
- **capabilities** (ServerCapabilities) - Required - Capabilities that a server may support.
- **serverInfo** (Implementation) - Required - Describes the name and version of an MCP implementation.
- **instructions** (string) - Optional - Instructions describing how to use the server and its features.
- **_meta** (object) - Optional - See General fields: `_meta` for notes on `_meta` usage.

#### Response Example
```json
{
  "protocolVersion": "string",
  "capabilities": {},
  "serverInfo": {
    "name": "string",
    "version": "string"
  },
  "instructions": "string"
}
```
```

--------------------------------

### Initialize Response

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

The server MUST respond with its own capabilities and information, including protocol version, server capabilities (logging, prompts, resources, tools), and server info.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "title": "Example Server Display Name",
      "version": "1.0.0"
    },
    "instructions": "Optional instructions for the client"
  }
}
```

--------------------------------

### Protocol Error Example

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Example of a protocol error response for an unknown tool, using JSON-RPC error code -32602.

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

--------------------------------

### Initialize Request

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

The client MUST send this `initialize` request as the first interaction. It includes the protocol version, client capabilities (roots, sampling, elicitation), and client information.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### tools/list

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Lists available tools. Supports pagination.

```APIDOC
## tools/list

### Description
Lists available tools. Supports pagination.

### Method
JSON-RPC request

### Endpoint
`tools/list`

### Parameters
#### Request Body
- **cursor** (string) - Optional - Cursor for pagination.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}
```

### Response
#### Success Response
- **tools** (array) - List of available tools.
- **nextCursor** (string) - Cursor for the next page.

#### Response Example
```json
{
  "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"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}
```
```

--------------------------------

### Request completion with context arguments

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/completion

For prompts with multiple arguments, the client includes previous completions in the context.arguments object to provide context. The response returns suggestions based on the provided context.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "framework",
      "value": "fla"
    },
    "context": {
      "arguments": {
        "language": "python"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}
```

--------------------------------

### Pagination Response Format

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination

Example JSON-RPC response with a nextCursor field indicating more results are available. The cursor is an opaque string token.

```json
{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}
```

--------------------------------

### Cancellation notification JSON-RPC message

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation

Example of a `notifications/cancelled` notification containing the request ID to cancel and an optional reason string. The reason can be logged or displayed.

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": "123",
    "reason": "User requested cancellation"
  }
}
```

--------------------------------

### prompts/list

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/prompts

Retrieves the list of available prompts from the server. Supports pagination.

```APIDOC
## prompts/list

### Description
Retrieves the list of available prompts from the server. This operation supports pagination.

### Method
JSON-RPC

### Endpoint
prompts/list

### Parameters
#### Request Body
- **cursor** (string) - Optional - Cursor for pagination.

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

### Response
#### Success Response
- **prompts** (array) - List of prompts.
  - **name** (string) - Name of the prompt.
  - **title** (string) - Title of the prompt.
  - **description** (string) - Description of the prompt.
  - **arguments** (array) - List of arguments.
    - **name** (string) - Argument name.
    - **description** (string) - Argument description.
    - **required** (boolean) - Whether the argument is required.
- **nextCursor** (string) - Cursor for the next page.

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "title": "Request Code Review",
        "description": "Asks the LLM to analyze code quality and suggest improvements",
        "arguments": [
          {
            "name": "code",
            "description": "The code to review",
            "required": true
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}
```

--------------------------------

### Return roots not supported error

Source: https://modelcontextprotocol.io/specification/2025-06-18/client/roots

Example error response when the client does not support roots. Uses standard JSON-RPC error code -32601 (Method not found).

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}
```

--------------------------------

### tools/list request and response

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Request and response pair for the tools/list method. The request supports pagination via an optional cursor parameter. The response returns a list of tools with their metadata and a nextCursor for further pages.

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

```

```json
{
  "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"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

```

--------------------------------

### prompts/get

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/prompts

Retrieves a specific prompt by name. Arguments may be auto-completed through the completion API.

```APIDOC
## prompts/get

### Description
Retrieves a specific prompt by name. Arguments may be auto-completed through the completion API.

### Method
JSON-RPC

### Endpoint
prompts/get

### Parameters
#### Request Body
- **name** (string) - Required - The name of the prompt to retrieve.
- **arguments** (object) - Optional - Arguments to customize the prompt.

### Request Example
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')"
    }
  }
}

### Response
#### Success Response
- **description** (string) - Description of the prompt.
- **messages** (array) - List of messages.
  - **role** (string) - Role of the message (e.g., "user").
  - **content** (object) - Content of the message.
    - **type** (string) - Type of content (e.g., "text").
    - **text** (string) - The text content.

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}
```

--------------------------------

### prompts/get request and response

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/prompts

Clients send a 'prompts/get' request to retrieve a specific prompt. Arguments may be auto-completed through the completion API. The response includes a description and an array of messages with role and content.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}
```

--------------------------------

### resources/templates/list

Source: https://modelcontextprotocol.io/specification/2025-06-18/schema

The resources/templates/list method is sent from the client to request a list of resource templates the server has. The request can include a cursor for pagination, and the response contains the list of resource templates.

```APIDOC
## resources/templates/list

### Description
Sent from the client to request a list of resource templates the server has.

### Method
resources/templates/list

### Request
#### ListResourceTemplatesRequest
- **method** (string) - Required - "resources/templates/list"
- **params.cursor** (string) - Optional - An opaque token representing the current pagination position. If provided, the server should return results starting after this cursor.

### Response
#### ListResourceTemplatesResult
- **_meta** (object) - Optional - See General fields: `_meta` for notes on `_meta` usage.
- **nextCursor** (string) - Optional - An opaque token representing the pagination position after the last returned result. If present, there may be more results available.
- **resourceTemplates** (array of ResourceTemplate) - Required - The list of resource templates.
- **[key: string]** (unknown) - Optional - Additional properties.

#### ResourceTemplate
- **name** (string) - Required - Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).
- **title** (string) - Optional - Intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology. If not provided, the name should be used for display (except for Tool, where `annotations.title` should be given precedence over using `name`, if present).
- **uriTemplate** (string) - Required - A URI template (according to RFC 6570) that can be used to construct resource URIs.
- **description** (string) - Optional - A description of what this template is for. This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model.
- **mimeType** (string) - Optional - The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type.
- **annotations** (Annotations) - Optional - Optional annotations for the client.
- **_meta** (object) - Optional - See General fields: `_meta` for notes on `_meta` usage.
```

--------------------------------

### JSON-RPC error response for resource not found

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Example JSON-RPC error response for a resource not found case. The error code -32002 is used for resource not found, and the data field includes the URI that caused the failure.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

```

--------------------------------

### GET MCP Endpoint (SSE Stream)

Source: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

Opens an SSE stream for server-to-client communication. The client must include an Accept header for text/event-stream. The server either returns a stream or 405. Supports resumability via Last-Event-ID.

```APIDOC
## [GET] MCP Endpoint (SSE Stream)

### Description
Opens an SSE stream to allow the server to send messages to the client without a prior POST. The client must include an Accept header listing text/event-stream.

### Method
GET

### Endpoint
MCP endpoint (as configured)

### Parameters
#### Headers
- **Accept** (string) - Required - Must include `text/event-stream`.
- **Last-Event-ID** (string) - Optional - Used to resume a broken connection; indicates the last event ID received.

### Response
#### Success Response (200)
- **Content-Type** (string) - Must be `text/event-stream`.
- **Body** (SSE stream) - Server may send JSON-RPC requests and notifications. Events may include an `id` field for resumability.

#### Error Response (405)
- **Content-Type** (string) - May be returned if the server does not offer an SSE stream at this endpoint.

```

--------------------------------

### resources/list Request and Response

Source: https://modelcontextprotocol.io/specification/2025-06-18/server/resources

Request and response pair for the resources/list method. The request supports pagination via an optional cursor parameter. The response contains an array of resources and an optional nextCursor for pagination.

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

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}
```
Tokens:
Raw