### Resource Reference Type Example

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

Example of a 'ref/resource' type used to reference a resource URI.

```json
{"type": "ref/resource", "uri": "file:///{path}"}
```

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

### Example HTTP GET Request with Access Token

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

Demonstrates a typical HTTP GET request to an MCP server, including the Authorization header with a Bearer token.

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

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

### Prompt Reference Type Example

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

Example of a 'ref/prompt' type used to reference a prompt by its name.

```json
{"type": "ref/prompt", "name": "code_review"}
```

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

### Single Project Root Definition

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

Example of a single root definition for a project directory, including its `uri` and `name`.

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

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

### Resource with Annotations

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

An example of a resource definition that includes annotations for audience, priority, and last modified timestamp.

```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"
  }
}
```

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

### GET /prompts/get

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

Retrieves a specific prompt by its name and optional arguments for templating.

```APIDOC
## GET /prompts/get

### Description
Used by the client to get a prompt provided by the server.

### Method
GET

### Endpoint
/prompts/get

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the prompt or prompt template.
- **arguments** (object) - Optional - Arguments to use for templating the prompt. The keys are strings and the values are strings.

### Request Example
```json
{
  "name": "examplePromptName",
  "arguments": {
    "key1": "value1",
    "key2": "value2"
  }
}
```

### Response
#### Success Response (200)
- **prompt** (string) - The content of the prompt.
- **arguments** (object) - The arguments used for templating the prompt.

#### Response Example
```json
{
  "prompt": "This is the content of the example prompt.",
  "arguments": {
    "key1": "value1",
    "key2": "value2"
  }
}
```
```

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

### Example Initialization Error Response

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

Illustrates a JSON RPC error response indicating an unsupported protocol version. This is useful for handling initial connection failures due to version mismatches.

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

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

### Image Content Example with Annotations

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

Demonstrates image content, including base64-encoded data and MIME type. Supports optional annotations for metadata like audience and priority.

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

}
```

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

### Text Content Example

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

Represents plain text content returned by a tool. This is a basic content type.

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

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

### Resource Link Example

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

Provides a link to an external resource, including URI, name, description, and MIME type. Supports annotations for metadata.

```json
{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust",
  "annotations": {
    "audience": ["assistant"],
    "priority": 0.9
  }
}
```

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

### Example Protocol Error

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

Illustrates a standard JSON-RPC error response for issues like unknown tools or invalid arguments.

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

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

### Multiple Repository Roots Definition

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

Example of defining multiple roots for different repositories, each with a `uri` and `name`.

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

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

### Listening for Messages from the Server (GET /mcp)

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

Clients can establish an SSE stream by issuing an HTTP GET request to the MCP endpoint. This allows the server to send JSON-RPC requests and notifications to the client without the client initiating a POST request. The server must respond with `Content-Type: text/event-stream` or `405 Method Not Allowed`.

```APIDOC
## GET /mcp

### Description
Establishes an SSE stream to receive messages from the server.

### Method
GET

### Endpoint
/mcp

### Headers
- **Accept** (string) - Required - Must list `text/event-stream` as a supported content type.

### Responses
#### Success Response (200 OK)
- **Content-Type**: `text/event-stream` - Indicates an SSE stream is established.
  - The stream may contain JSON-RPC requests and notifications.
  - The server MUST NOT send a JSON-RPC response unless resuming a stream.
  - The server MAY close the SSE stream at any time.

#### Error Response (405 Method Not Allowed)
- Returned if the server does not offer an SSE stream at this endpoint.

### Response Example (SSE Stream)
```
id: 1
data: {"jsonrpc": "2.0", "method": "update", "params": {"data": "new data"}}

```
```

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

### Image Content Example

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

Allows including visual information. Data must be base64-encoded with a valid MIME type.

```json
{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}
```

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

### Tool Definition with Input and Output Schemas

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

Defines a tool's name, title, description, and schemas for input and output validation. This example shows a weather data retriever.

```json
{
  "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"]
  }
}
```

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

### Getting a Prompt

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

Clients can retrieve the content and structure of a specific prompt by its name, optionally providing arguments for completion.

```APIDOC
## Get Prompt API

### Description
Retrieves the details and messages for a specific prompt, allowing for argument pre-filling.

### Method
POST

### Endpoint
/prompts/get

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - The method name, must be "prompts/get".
- **params** (object) - Required - Parameters for the method.
  - **name** (string) - Required - The unique name of the prompt to retrieve.
  - **arguments** (object) - Optional - Key-value pairs of arguments to pre-fill for the prompt.

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

### Response
#### Success Response (200)
- **jsonrpc** (string) - Specifies the JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The result of the operation.
  - **description** (string) - Description of the prompt.
  - **messages** (array) - A list of messages that form the prompt.
    - **role** (string) - The role of the message sender (e.g., "user", "assistant").
    - **content** (object) - The content of the message.
      - **type** (string) - The type of content (e.g., "text").
      - **text** (string) - The actual text content of the message.

#### Response Example
```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')"
        }
      }
    ]
  }
}
```
```

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

### Example Tool Execution Error

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

Shows how tool execution errors are reported within the result object, indicating failures like API issues or invalid data.

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

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

### Declare Resources Capability

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

Servers MUST declare the 'resources' capability to indicate support for exposing resources. This example shows both 'subscribe' and 'listChanged' features enabled.

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

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

### String Schema Example

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

Defines a string schema with validation for minimum/maximum length and specific formats like email or URI. Use for text-based inputs.

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

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

### Request Completions for Prompt Argument

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

Send a 'completion/complete' request to get suggestions for a specific prompt argument. Include the argument name and its current value.

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

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

### Number Schema Example

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

Defines a number schema with validation for minimum and maximum values. Use for numerical inputs, including integers.

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

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

### Embedded Resource Example

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

References server-side resources. Must include a valid URI, MIME type, and either text or base64-encoded blob data.

```json
{
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "mimeType": "text/plain",
    "text": "Resource content"
  }
}
```

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

### Elicitation Response (Structured Data Accept)

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

Example of a successful response to a structured data elicitation request, containing the user's input.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "action": "accept",
    "content": {
      "name": "Monalisa Octocat",
      "email": "octocat@github.com",
      "age": 30
    }
  }
}
```

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

### Valid Tool Response with Structured Content

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

An example of a valid JSON RPC response from a tool, including both text content and structured content that conforms to the output schema.

```json
{
  "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
    }
  }
}
```

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

### Enum Schema Example

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

Defines a string schema with a predefined list of allowed values (enum) and their corresponding display names (enumNames). Use for selecting from a fixed set of options.

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

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

### Initialization Phase

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

The client initiates the connection by sending an 'initialize' request to negotiate protocol version, capabilities, and client information. The server responds with its capabilities and information.

```APIDOC
## POST /initialize

### Description
Initiates the Model Context Protocol connection by negotiating protocol version, capabilities, and client information.

### Method
POST

### Endpoint
/

### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, must be "2.0".
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - The method name, must be "initialize".
- **params** (object) - Required - Parameters for the initialize request.
  - **protocolVersion** (string) - Required - The protocol version supported by the client (e.g., "2025-06-18").
  - **capabilities** (object) - Required - Client capabilities.
    - **roots** (object) - Optional - Roots capabilities.
      - **listChanged** (boolean) - Optional - Indicates if the client supports root list change notifications.
    - **sampling** (object) - Optional - Sampling capabilities.
    - **elicitation** (object) - Optional - Elicitation capabilities.
  - **clientInfo** (object) - Optional - Client implementation information.
    - **name** (string) - Required - The name of the client.
    - **title** (string) - Optional - The display name of the client.
    - **version** (string) - Optional - The version of the client.

### Request Example
```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"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version, must be "2.0".
- **id** (integer) - The request ID.
- **result** (object) - The result of the initialization.
  - **protocolVersion** (string) - The protocol version supported by the server.
  - **capabilities** (object) - Server capabilities.
    - **logging** (object) - Optional - Logging capabilities.
    - **prompts** (object) - Optional - Prompts capabilities.
      - **listChanged** (boolean) - Optional - Indicates if the server supports prompt list change notifications.
    - **resources** (object) - Optional - Resources capabilities.
      - **subscribe** (boolean) - Optional - Indicates if the server supports resource subscription.
      - **listChanged** (boolean) - Optional - Indicates if the server supports resource list change notifications.
    - **tools** (object) - Optional - Tools capabilities.
      - **listChanged** (boolean) - Optional - Indicates if the server supports tool list change notifications.
  - **serverInfo** (object) - Optional - Server implementation information.
    - **name** (string) - Required - The name of the server.
    - **title** (string) - Optional - The display name of the server.
    - **version** (string) - Optional - The version of the server.
  - **instructions** (string) - Optional - Instructions for the client.

#### Response Example
```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"
  }
}
```
```

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

### Boolean Schema Example

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

Defines a boolean schema with a default value. Use for true/false inputs.

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

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

### Text Content Example

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

Represents plain text messages. Use for natural language interactions.

```json
{
  "type": "text",
  "text": "The text content of the message"
}
```

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

### Tools List Response

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

The server responds with a list of available tools, including their names, descriptions, and input schemas. 'nextCursor' is provided for pagination.

```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"
  }
}
```

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

### Client Initialize Request

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

The client's `initialize` request, sent first to establish protocol version compatibility, negotiate capabilities, and share implementation details.

```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"
    }
  }
}
```

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

### Server Initialize Response

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

The server's response to the `initialize` request, containing its capabilities, server information, and optional instructions for the client.

```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"
  }
}
```

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

### MCP Sequence Diagram

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

Illustrates the initialization and interaction flow between Host, Client, and Server in the Model Context Protocol, including capability negotiation and active session loops.

```mermaid
sequenceDiagram
    participant Host
    participant Client
    participant Server

    Host->>+Client: Initialize client
    Client->>+Server: Initialize session with capabilities
    Server-->>Client: Respond with supported capabilities

    Note over Host,Server: Active Session with Negotiated Features

    loop Client Requests
        Host->>Client: User- or model-initiated action
        Client->>Server: Request (tools/resources)
        Server-->>Client: Response
        Client-->>Host: Update UI or respond to model
    end

    loop Server Requests
        Server->>Client: Request (sampling)
        Client->>Host: Forward to AI
        Host-->>Client: AI response
        Client-->>Server: Response
    end

    loop Notifications
        Server--)Client: Resource updates
        Client--)Server: Status changes
    end

    Host->>Client: Terminate
    Client->>-Server: End session
    deactivate Server
```

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

### Request to List Resource Templates

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

Clients send a 'resources/templates/list' JSON-RPC request to discover parameterized resources. Pagination is supported.

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

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

### Initialize Request

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

The client sends an InitializeRequest to the server to initiate the connection and establish protocol version and capabilities.

```APIDOC
## POST /initialize

### Description
Initiates the Model Context Protocol connection by sending client capabilities and information to the server.

### Method
POST

### Endpoint
/initialize

### Request Body
- **method** (string) - Required - Must be "initialize".
- **params** (object) - Required - Contains initialization parameters.
  - **protocolVersion** (string) - Required - The latest version of the Model Context Protocol the client supports.
  - **capabilities** (ClientCapabilities) - Required - The capabilities of the client.
  - **clientInfo** (Implementation) - Required - Information about the client implementation.

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

### Response
#### Success Response (200)
- **result** (InitializeResult) - The result of the initialization.
- **id** (integer) - The ID of the request.

#### Response Example
```json
{
  "result": {},
  "id": 1
}
```
```

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

### Roots Not Supported Error

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

Example of a JSON-RPC error response (-32601 Method not found) when a client does not support the roots capability.

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

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

### Listing Available Tools

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

Clients can discover available tools by sending a `tools/list` request. This operation supports pagination.

```APIDOC
## POST /tools/list

### Description
Retrieves a list of available tools that can be invoked by language models. Supports pagination.

### Method
POST

### Endpoint
/tools/list

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

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

### Response
#### Success Response (200)
- **tools** (array) - A list of available tool objects.
- **nextCursor** (string) - A cursor for fetching the next page of results, if available.

#### 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"
  }
}
```
```

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

### Resource Parameter in Authorization Request

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

Example of how the 'resource' parameter should be URL-encoded when included in an authorization request to specify the target MCP server.

```plaintext
&resource=https%3A%2F%2Fmcp.example.com
```

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

### Listing Resource Templates

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

Servers can expose parameterized resources using resource templates. Clients can list these templates using the `resources/templates/list` request, which also supports pagination.

```APIDOC
## Resource Templates

Resource templates allow servers to expose parameterized resources using [URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be auto-completed through [the completion API](/specification/2025-06-18/server/utilities/completion). This operation supports [pagination](/specification/2025-06-18/server/utilities/pagination).

**Request:**

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

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}
```
```

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

### Listing Resources

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

Clients can discover available resources by sending a `resources/list` request. This operation supports pagination.

```APIDOC
## Listing Resources

To discover available resources, clients send a `resources/list` request. This operation supports [pagination](/specification/2025-06-18/server/utilities/pagination).

**Request:**

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

**Response:**

```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"
  }
}
```
```

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

### Embedded Resource Example

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

Embeds a resource directly within the tool result, including its URI, MIME type, content, and annotations. Requires the 'resources' capability.

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

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

### POST /completion/complete

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

Requests completion options based on a given prompt reference and argument.

```APIDOC
## POST /completion/complete

### Description
Requests completion options based on a given prompt reference and argument. This endpoint is used to generate text completions.

### Method
POST

### Endpoint
/completion/complete

### Request Body
- **method** (string) - Required - Must be "completion/complete".
- **params** (object) - Required - Parameters for the completion request.
  - **ref** (PromptReference | ResourceTemplateReference) - Required - Reference to the prompt or resource template.
  - **argument** (object) - Required - The argument's information.
    - **name** (string) - Required - The name of the argument.
    - **value** (string) - Required - The value of the argument.
  - **context** (object) - Optional - Context for the completion.
    - **arguments** (object) - Optional - Additional arguments for the context.
      - **[key]** (string) - The key of the argument.

### Request Example
```json
{
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "prompt",
      "id": "some-prompt-id"
    },
    "argument": {
      "name": "input_text",
      "value": "The quick brown fox"
    },
    "context": {
      "arguments": {
        "max_tokens": "100"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **completions** (array) - A list of completion options.
  - **text** (string) - The completion text.
  - **description** (string) - A description of the completion.
  - **type** (string) - The type of completion.
  - **stop** (boolean) - Indicates if this is a stop completion.

#### Response Example
```json
{
  "completions": [
    {
      "text": "jumps over the lazy dog.",
      "description": "Completes the sentence.",
      "type": "text",
      "stop": false
    }
  ]
}
```
```

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

### Model Hints Configuration

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

Use this JSON structure to provide hints for model selection, allowing clients to suggest preferred models or families. Hints are treated as substrings for flexible matching, and multiple hints are evaluated in order of preference.

```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
}
```

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

### Request to List Resources

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

Clients send a 'resources/list' JSON-RPC request to discover available resources. Pagination is supported via the 'cursor' parameter.

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

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

### Tools List Request

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

Clients send a 'tools/list' request to discover available tools. Pagination is supported via the 'cursor' parameter.

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

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

### Listing Prompts

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

Clients can retrieve a list of available prompts from the server. This operation supports pagination.

```APIDOC
## Prompts List API

### Description
Retrieves a list of available prompts from the server. Supports pagination.

### Method
POST

### Endpoint
/prompts/list

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version.
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - The method name, must be "prompts/list".
- **params** (object) - Optional - Parameters for the method.
  - **cursor** (string) - Optional - A cursor for pagination to fetch the next page of results.

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

### Response
#### Success Response (200)
- **jsonrpc** (string) - Specifies the JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The result of the operation.
  - **prompts** (array) - A list of available prompts.
    - **name** (string) - Unique identifier for the prompt.
    - **title** (string) - Human-readable name of the prompt.
    - **description** (string) - Human-readable description of the prompt.
    - **arguments** (array) - List of arguments required by the prompt.
      - **name** (string) - Name of the argument.
      - **description** (string) - Description of the argument.
      - **required** (boolean) - Indicates if the argument is required.
  - **nextCursor** (string) - A cursor for fetching the next page of results, if available.

#### Response Example
```json
{
  "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"
  }
}
```
```

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

### Completion Response with Contextual Suggestions

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

The server returns refined suggestions based on the provided context, such as previously resolved arguments.

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

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

### List Resource Templates

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

Requests a list of resource templates available on the server. Supports pagination using a cursor.

```APIDOC
## POST /resources/templates/list

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

### Method
POST

### Endpoint
/resources/templates/list

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

### Request Example
```json
{
  "method": "resources/templates/list",
  "params": {
    "cursor": "some_opaque_cursor_token"
  }
}
```

### Response
#### Success Response (200)
- **templates** (array) - A list of resource templates.
- **next_cursor** (string) - An opaque token for the next page of results, or null if there are no more results.

#### Response Example
```json
{
  "templates": [
    {
      "id": "template-1",
      "name": "Example Template",
      "description": "This is an example resource template."
    }
  ],
  "next_cursor": "another_opaque_cursor_token"
}
```
```

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

### JSON-RPC Error Response Example

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

Servers should return this standard JSON-RPC error format for common failure cases like resource not found. Ensure the 'code', 'message', and 'data' fields accurately reflect the error.

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

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

### roots/list

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

Sent from the server to request a list of root URIs from the client. Roots allow servers to ask for specific directories or files to operate on. A common example for roots is providing a set of repositories or directories a server should operate on. This request is typically used when the server needs to understand the file system structure or access specific locations that the client has permission to read from.

```APIDOC
## `roots/list`

### Description
Sent from the server to request a list of root URIs from the client. Roots allow servers to ask for specific directories or files to operate on. A common example for roots is providing a set of repositories or directories a server should operate on. This request is typically used when the server needs to understand the file system structure or access specific locations that the client has permission to read from.

### Method
POST

### Endpoint
/roots/list

### Request Body
- **method** (string) - Required - Must be "roots/list"
- **params** (object) - Optional - Parameters for the request.
  - **_meta** (object) - Optional - See General fields: `_meta` for notes on `_meta` usage.
    - **progressToken** (ProgressToken) - Optional - If specified, the caller is requesting out-of-band progress notifications for this request. The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.
    - **[key: string]** (unknown) - Optional - Additional metadata.
  - **[key: string]** (unknown) - Optional - Additional parameters.
```

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

### POST /prompts/list

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

Requests a list of prompts and prompt templates available on the server. Supports pagination.

```APIDOC
## POST /prompts/list

### Description
Sent from the client to request a list of prompts and prompt templates the server has.

### Method
POST

### Endpoint
/prompts/list

### Request Body
- **params** (object) - Optional - Contains pagination parameters.
  - **cursor** (string) - Optional - An opaque token representing the current pagination position. If provided, the server should return results starting after this cursor.
- **method** (string) - Required - Must be "prompts/list".

### Request Example
```json
{
  "method": "prompts/list",
  "params": {
    "cursor": "some_opaque_cursor_token"
  }
}
```

### Response
#### Success Response (200)
- **prompts** (array) - A list of prompts.
- **next_cursor** (string) - An opaque token for fetching the next page of results, or null if there are no more results.

#### Response Example
```json
{
  "prompts": [
    {
      "id": "prompt_123",
      "name": "Example Prompt",
      "template": "This is a template for prompt {{variable}}"
    }
  ],
  "next_cursor": "another_opaque_cursor_token"
}
```
```

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

### Response with Prompt Content

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

The server's response to a 'prompts/get' request contains the prompt's description and a list of messages. Each message includes a role ('user' or 'assistant') and content, which can be text or other types.

```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')"
        }
      }
    ]
  }
}
```

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

### Response with Prompt List

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

The server's response to a 'prompts/list' request includes an array of available prompts, each with a name, title, description, and arguments. 'nextCursor' is provided for fetching subsequent pages.

```json
{
  "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"
  }
}
```

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

### Create Message (Sampling Request)

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

Servers send a `sampling/createMessage` request to initiate a language model generation.

```APIDOC
## POST /sampling/createMessage

### Description
Requests a language model generation from the client.

### Method
POST

### Endpoint
/sampling/createMessage

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC protocol version.
- **id** (integer) - Required - Unique identifier for the request.
- **method** (string) - Required - The method name, must be `sampling/createMessage`.
- **params** (object) - Required - Parameters for the `createMessage` method.
  - **messages** (array) - Required - An array of message objects representing the conversation history.
    - **role** (string) - Required - The role of the message sender (e.g., `user`, `assistant`).
    - **content** (object) - Required - The content of the message.
      - **type** (string) - Required - The type of content (`text`, `image`, `audio`).
      - **text** (string) - Optional - The text content of the message.
      - **data** (string) - Optional - Base64-encoded data for image or audio content.
      - **mimeType** (string) - Optional - The MIME type of the data (e.g., `image/jpeg`, `audio/wav`).
  - **modelPreferences** (object) - Optional - Preferences for model selection.
    - **hints** (array) - Optional - An array of model hints.
      - **name** (string) - Required - The name of the preferred model.
    - **intelligencePriority** (number) - Optional - Priority for model intelligence (0-1).
    - **speedPriority** (number) - Optional - Priority for model speed (0-1).
    - **costPriority** (number) - Optional - Priority for model cost (0-1).
  - **systemPrompt** (string) - Optional - A system prompt to guide the model's behavior.
  - **maxTokens** (integer) - Optional - The maximum number of tokens to generate.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC protocol version.
- **id** (integer) - Unique identifier for the response, matching the request ID.
- **result** (object) - The result of the operation.
  - **role** (string) - The role of the message sender (e.g., `assistant`).
  - **content** (object) - The content of the generated message.
    - **type** (string) - The type of content (`text`, `image`, `audio`).
    - **text** (string) - The text content of the message.
    - **data** (string) - Base64-encoded data for image or audio content.
    - **mimeType** (string) - The MIME type of the data.
  - **model** (string) - The name of the model used for generation.
  - **stopReason** (string) - The reason the generation stopped (e.g., `endTurn`).

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}
```
```