An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.
JavaScript aicursorcursor-aicursorailovablelovable-devroocodetask-managertaskstasks-listwindsurfwindsurf-ai
adds mcp protocol spec and docs.
Eyal Toledano57f655affd87
diff --git a/docs/mcp-protocol-docs.txt b/docs/mcp-protocol-repo.txtsimilarity index 100%rename from docs/mcp-protocol-docs.txtrename to docs/mcp-protocol-repo.txtdiff --git a/docs/mcp-protocol-spec.txt b/docs/mcp-protocol-spec.txtnew file mode 100644index 00000000..aa5c3215--- /dev/null+++ b/docs/mcp-protocol-spec.txt@@ -0,0 +1,9589 @@+Directory Structure:++└── ./+ ├── docs+ │ ├── resources+ │ │ └── _index.md+ │ └── specification+ │ ├── 2024-11-05+ │ │ ├── architecture+ │ │ │ └── _index.md+ │ │ ├── basic+ │ │ │ ├── utilities+ │ │ │ │ ├── _index.md+ │ │ │ │ ├── cancellation.md+ │ │ │ │ ├── ping.md+ │ │ │ │ └── progress.md+ │ │ │ ├── _index.md+ │ │ │ ├── lifecycle.md+ │ │ │ ├── messages.md+ │ │ │ └── transports.md+ │ │ ├── client+ │ │ │ ├── _index.md+ │ │ │ ├── roots.md+ │ │ │ └── sampling.md+ │ │ ├── server+ │ │ │ ├── utilities+ │ │ │ │ ├── _index.md+ │ │ │ │ ├── completion.md+ │ │ │ │ ├── logging.md+ │ │ │ │ └── pagination.md+ │ │ │ ├── _index.md+ │ │ │ ├── prompts.md+ │ │ │ ├── resource-picker.png+ │ │ │ ├── resources.md+ │ │ │ ├── slash-command.png+ │ │ │ └── tools.md+ │ │ └── _index.md+ │ ├── 2025-03-26+ │ │ ├── architecture+ │ │ │ └── _index.md+ │ │ ├── basic+ │ │ │ ├── utilities+ │ │ │ │ ├── _index.md+ │ │ │ │ ├── cancellation.md+ │ │ │ │ ├── ping.md+ │ │ │ │ └── progress.md+ │ │ │ ├── _index.md+ │ │ │ ├── authorization.md+ │ │ │ ├── lifecycle.md+ │ │ │ └── transports.md+ │ │ ├── client+ │ │ │ ├── _index.md+ │ │ │ ├── roots.md+ │ │ │ └── sampling.md+ │ │ ├── server+ │ │ │ ├── utilities+ │ │ │ │ ├── _index.md+ │ │ │ │ ├── completion.md+ │ │ │ │ ├── logging.md+ │ │ │ │ └── pagination.md+ │ │ │ ├── _index.md+ │ │ │ ├── prompts.md+ │ │ │ ├── resource-picker.png+ │ │ │ ├── resources.md+ │ │ │ ├── slash-command.png+ │ │ │ └── tools.md+ │ │ ├── _index.md+ │ │ └── changelog.md+ │ ├── _index.md+ │ ├── contributing.md+ │ └── versioning.md+ ├── schema+ │ ├── 2024-11-05+ │ │ └── schema.ts+ │ └── 2025-03-26+ │ └── schema.ts+ ├── scripts+ │ └── validate_examples.ts+ ├── site+ │ └── layouts+ │ └── index.html+ └── README.md++++---+File: /docs/resources/_index.md+---++---+title: "Additional Resources"+weight: 20+breadcrumbs: false+sidebar:+ exclude: true+---++The Model Context Protocol (MCP) provides multiple resources for documentation and+implementation:++- **User Documentation**: Visit+ [modelcontextprotocol.io](https://modelcontextprotocol.io) for comprehensive+ user-facing documentation+- **Python SDK**: The Python implementation is available at+ [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) -+ [Issues](https://github.com/modelcontextprotocol/python-sdk/issues)+- **Specification**: The core specification is available at+ [github.com/modelcontextprotocol/specification](https://github.com/modelcontextprotocol/specification) -+ [Discussions](https://github.com/modelcontextprotocol/specification/discussions)+- **TypeScript SDK**: The TypeScript implementation can be found at+ [github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) -+ [Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues)++For questions or discussions, please open a discussion in the appropriate GitHub+repository based on your implementation or use case. You can also visit the+[Model Context Protocol organization on GitHub](https://github.com/modelcontextprotocol)+to see all repositories and ongoing development.++++---+File: /docs/specification/2024-11-05/architecture/_index.md+---++---+title: Architecture+cascade:+ type: docs+weight: 1+---++The Model Context Protocol (MCP) follows a client-host-server architecture where each+host can run multiple client instances. This architecture enables users to integrate AI+capabilities across applications while maintaining clear security boundaries and+isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused+on context exchange and sampling coordination between clients and servers.++## Core Components++```mermaid+graph LR+ subgraph "Application Host Process"+ H[Host]+ C1[Client 1]+ C2[Client 2]+ C3[Client 3]+ H --> C1+ H --> C2+ H --> C3+ end++ subgraph "Local machine"+ S1[Server 1<br>Files & Git]+ S2[Server 2<br>Database]+ R1[("Local<br>Resource A")]+ R2[("Local<br>Resource B")]++ C1 --> S1+ C2 --> S2+ S1 <--> R1+ S2 <--> R2+ end++ subgraph "Internet"+ S3[Server 3<br>External APIs]+ R3[("Remote<br>Resource C")]++ C3 --> S3+ S3 <--> R3+ end+```++### Host++The host process acts as the container and coordinator:++- Creates and manages multiple client instances+- Controls client connection permissions and lifecycle+- Enforces security policies and consent requirements+- Handles user authorization decisions+- Coordinates AI/LLM integration and sampling+- Manages context aggregation across clients++### Clients++Each client is created by the host and maintains an isolated server connection:++- Establishes one stateful session per server+- Handles protocol negotiation and capability exchange+- Routes protocol messages bidirectionally+- Manages subscriptions and notifications+- Maintains security boundaries between servers++A host application creates and manages multiple clients, with each client having a 1:1+relationship with a particular server.++### Servers++Servers provide specialized context and capabilities:++- Expose resources, tools and prompts via MCP primitives+- Operate independently with focused responsibilities+- Request sampling through client interfaces+- Must respect security constraints+- Can be local processes or remote services++## Design Principles++MCP is built on several key design principles that inform its architecture and+implementation:++1. **Servers should be extremely easy to build**++ - Host applications handle complex orchestration responsibilities+ - Servers focus on specific, well-defined capabilities+ - Simple interfaces minimize implementation overhead+ - Clear separation enables maintainable code++2. **Servers should be highly composable**++ - Each server provides focused functionality in isolation+ - Multiple servers can be combined seamlessly+ - Shared protocol enables interoperability+ - Modular design supports extensibility++3. **Servers should not be able to read the whole conversation, nor "see into" other+ servers**++ - Servers receive only necessary contextual information+ - Full conversation history stays with the host+ - Each server connection maintains isolation+ - Cross-server interactions are controlled by the host+ - Host process enforces security boundaries++4. **Features can be added to servers and clients progressively**+ - Core protocol provides minimal required functionality+ - Additional capabilities can be negotiated as needed+ - Servers and clients evolve independently+ - Protocol designed for future extensibility+ - Backwards compatibility is maintained++## Message Types++MCP defines three core message types based on+[JSON-RPC 2.0](https://www.jsonrpc.org/specification):++- **Requests**: Bidirectional messages with method and parameters expecting a response+- **Responses**: Successful results or errors matching specific request IDs+- **Notifications**: One-way messages requiring no response++Each message type follows the JSON-RPC 2.0 specification for structure and delivery+semantics.++## Capability Negotiation++The Model Context Protocol uses a capability-based negotiation system where clients and+servers explicitly declare their supported features during initialization. Capabilities+determine which protocol features and primitives are available during a session.++- Servers declare capabilities like resource subscriptions, tool support, and prompt+ templates+- Clients declare capabilities like sampling support and notification handling+- Both parties must respect declared capabilities throughout the session+- Additional capabilities can be negotiated through extensions to the protocol++```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+```++Each capability unlocks specific protocol features for use during the session. For+example:++- Implemented [server features]({{< ref "/specification/2024-11-05/server" >}}) must be+ advertised in the server's capabilities+- Emitting resource subscription notifications requires the server to declare+ subscription support+- Tool invocation requires the server to declare tool capabilities+- [Sampling]({{< ref "/specification/2024-11-05/client" >}}) requires the client to+ declare support in its capabilities++This capability negotiation ensures clients and servers have a clear understanding of+supported functionality while maintaining protocol extensibility.++++---+File: /docs/specification/2024-11-05/basic/utilities/_index.md+---++---+title: Utilities+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++These optional features enhance the base protocol functionality with various utilities.++{{< cards >}} {{< card link="ping" title="Ping" icon="status-online" >}}+{{< card link="cancellation" title="Cancellation" icon="x" >}}+{{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}}++++---+File: /docs/specification/2024-11-05/basic/utilities/cancellation.md+---++---+title: Cancellation+weight: 10+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) supports optional cancellation of in-progress requests+through notification messages. Either side can send a cancellation notification to+indicate that a previously-issued request should be terminated.++## Cancellation Flow++When a party wants to cancel an in-progress request, it sends a `notifications/cancelled`+notification containing:++- The ID of the request to cancel+- An optional reason string that can be logged or displayed++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/cancelled",+ "params": {+ "requestId": "123",+ "reason": "User requested cancellation"+ }+}+```++## Behavior Requirements++1. Cancellation notifications **MUST** only reference requests that:+ - Were previously issued in the same direction+ - Are believed to still be in-progress+2. The `initialize` request **MUST NOT** be cancelled by clients+3. Receivers of cancellation notifications **SHOULD**:+ - Stop processing the cancelled request+ - Free associated resources+ - Not send a response for the cancelled request+4. Receivers **MAY** ignore cancellation notifications if:+ - The referenced request is unknown+ - Processing has already completed+ - The request cannot be cancelled+5. The sender of the cancellation notification **SHOULD** ignore any response to the+ request that arrives afterward++## Timing Considerations++Due to network latency, cancellation notifications may arrive after request processing+has completed, and potentially after a response has already been sent.++Both parties **MUST** handle these race conditions gracefully:++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Client->>Server: Request (ID: 123)+ Note over Server: Processing starts+ Client--)Server: notifications/cancelled (ID: 123)+ alt+ Note over Server: Processing may have<br/>completed before<br/>cancellation arrives+ else If not completed+ Note over Server: Stop processing+ end+```++## Implementation Notes++- Both parties **SHOULD** log cancellation reasons for debugging+- Application UIs **SHOULD** indicate when cancellation is requested++## Error Handling++Invalid cancellation notifications **SHOULD** be ignored:++- Unknown request IDs+- Already completed requests+- Malformed notifications++This maintains the "fire and forget" nature of notifications while allowing for race+conditions in asynchronous communication.++++---+File: /docs/specification/2024-11-05/basic/utilities/ping.md+---++---+title: Ping+weight: 5+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol includes an optional ping mechanism that allows either party+to verify that their counterpart is still responsive and the connection is alive.++## Overview++The ping functionality is implemented through a simple request/response pattern. Either+the client or server can initiate a ping by sending a `ping` request.++## Message Format++A ping request is a standard JSON-RPC request with no parameters:++```json+{+ "jsonrpc": "2.0",+ "id": "123",+ "method": "ping"+}+```++## Behavior Requirements++1. The receiver **MUST** respond promptly with an empty response:++```json+{+ "jsonrpc": "2.0",+ "id": "123",+ "result": {}+}+```++2. If no response is received within a reasonable timeout period, the sender **MAY**:+ - Consider the connection stale+ - Terminate the connection+ - Attempt reconnection procedures++## Usage Patterns++```mermaid+sequenceDiagram+ participant Sender+ participant Receiver++ Sender->>Receiver: ping request+ Receiver->>Sender: empty response+```++## Implementation Considerations++- Implementations **SHOULD** periodically issue pings to detect connection health+- The frequency of pings **SHOULD** be configurable+- Timeouts **SHOULD** be appropriate for the network environment+- Excessive pinging **SHOULD** be avoided to reduce network overhead++## Error Handling++- Timeouts **SHOULD** be treated as connection failures+- Multiple failed pings **MAY** trigger connection reset+- Implementations **SHOULD** log ping failures for diagnostics++++---+File: /docs/specification/2024-11-05/basic/utilities/progress.md+---++---+title: Progress+weight: 30+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) supports optional progress tracking for long-running+operations through notification messages. Either side can send progress notifications to+provide updates about operation status.++## Progress Flow++When a party wants to _receive_ progress updates for a request, it includes a+`progressToken` in the request metadata.++- Progress tokens **MUST** be a string or integer value+- Progress tokens can be chosen by the sender using any means, but **MUST** be unique+ across all active requests.++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "some_method",+ "params": {+ "_meta": {+ "progressToken": "abc123"+ }+ }+}+```++The receiver **MAY** then send progress notifications containing:++- The original progress token+- The current progress value so far+- An optional "total" value++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/progress",+ "params": {+ "progressToken": "abc123",+ "progress": 50,+ "total": 100+ }+}+```++- The `progress` value **MUST** increase with each notification, even if the total is+ unknown.+- The `progress` and the `total` values **MAY** be floating point.++## Behavior Requirements++1. Progress notifications **MUST** only reference tokens that:++ - Were provided in an active request+ - Are associated with an in-progress operation++2. Receivers of progress requests **MAY**:+ - Choose not to send any progress notifications+ - Send notifications at whatever frequency they deem appropriate+ - Omit the total value if unknown++```mermaid+sequenceDiagram+ participant Sender+ participant Receiver++ Note over Sender,Receiver: Request with progress token+ Sender->>Receiver: Method request with progressToken++ Note over Sender,Receiver: Progress updates+ loop Progress Updates+ Receiver-->>Sender: Progress notification (0.2/1.0)+ Receiver-->>Sender: Progress notification (0.6/1.0)+ Receiver-->>Sender: Progress notification (1.0/1.0)+ end++ Note over Sender,Receiver: Operation complete+ Receiver->>Sender: Method response+```++## Implementation Notes++- Senders and receivers **SHOULD** track active progress tokens+- Both parties **SHOULD** implement rate limiting to prevent flooding+- Progress notifications **MUST** stop after completion++++---+File: /docs/specification/2024-11-05/basic/_index.md+---++---+title: Base Protocol+cascade:+ type: docs+weight: 2+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++All messages between MCP clients and servers **MUST** follow the+[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines+three fundamental types of messages:++| Type | Description | Requirements |+| --------------- | -------------------------------------- | -------------------------------------- |+| `Requests` | Messages sent to initiate an operation | Must include unique ID and method name |+| `Responses` | Messages sent in reply to requests | Must include same ID as request |+| `Notifications` | One-way messages with no reply | Must not include an ID |++**Responses** are further sub-categorized as either **successful results** or **errors**.+Results can follow any JSON object structure, while errors must include an error code and+message at minimum.++## Protocol Layers++The Model Context Protocol consists of several key components that work together:++- **Base Protocol**: Core JSON-RPC message types+- **Lifecycle Management**: Connection initialization, capability negotiation, and+ session control+- **Server Features**: Resources, prompts, and tools exposed by servers+- **Client Features**: Sampling and root directory lists provided by clients+- **Utilities**: Cross-cutting concerns like logging and argument completion++All implementations **MUST** support the base protocol and lifecycle management+components. Other components **MAY** be implemented based on the specific needs of the+application.++These protocol layers establish clear separation of concerns while enabling rich+interactions between clients and servers. The modular design allows implementations to+support exactly the features they need.++See the following pages for more details on the different components:++{{< cards >}}+{{< card link="/specification/2024-11-05/basic/lifecycle" title="Lifecycle" icon="refresh" >}}+{{< card link="/specification/2024-11-05/server/resources" title="Resources" icon="document" >}}+{{< card link="/specification/2024-11-05/server/prompts" title="Prompts" icon="chat-alt-2" >}}+{{< card link="/specification/2024-11-05/server/tools" title="Tools" icon="adjustments" >}}+{{< card link="/specification/2024-11-05/server/utilities/logging" title="Logging" icon="annotation" >}}+{{< card link="/specification/2024-11-05/client/sampling" title="Sampling" icon="code" >}}+{{< /cards >}}++## Auth++Authentication and authorization are not currently part of the core MCP specification,+but we are considering ways to introduce them in future. Join us in+[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)+to help shape the future of the protocol!++Clients and servers **MAY** negotiate their own custom authentication and authorization+strategies.++## Schema++The full specification of the protocol is defined as a+[TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.ts).+This is the source of truth for all protocol messages and structures.++There is also a+[JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.json),+which is automatically generated from the TypeScript source of truth, for use with+various automated tooling.++++---+File: /docs/specification/2024-11-05/basic/lifecycle.md+---++---+title: Lifecycle+type: docs+weight: 30+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server+connections that ensures proper capability negotiation and state management.++1. **Initialization**: Capability negotiation and protocol version agreement+2. **Operation**: Normal protocol communication+3. **Shutdown**: Graceful termination of the connection++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Note over Client,Server: Initialization Phase+ activate Client+ Client->>+Server: initialize request+ Server-->>Client: initialize response+ Client--)Server: initialized notification++ Note over Client,Server: Operation Phase+ rect rgb(200, 220, 250)+ note over Client,Server: Normal protocol operations+ end++ Note over Client,Server: Shutdown+ Client--)-Server: Disconnect+ deactivate Server+ Note over Client,Server: Connection closed+```++## Lifecycle Phases++### Initialization++The initialization phase **MUST** be the first interaction between client and server.+During this phase, the client and server:++- Establish protocol version compatibility+- Exchange and negotiate capabilities+- Share implementation details++The client **MUST** initiate this phase by sending an `initialize` request containing:++- Protocol version supported+- Client capabilities+- Client implementation information++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "initialize",+ "params": {+ "protocolVersion": "2024-11-05",+ "capabilities": {+ "roots": {+ "listChanged": true+ },+ "sampling": {}+ },+ "clientInfo": {+ "name": "ExampleClient",+ "version": "1.0.0"+ }+ }+}+```++The server **MUST** respond with its own capabilities and information:++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "protocolVersion": "2024-11-05",+ "capabilities": {+ "logging": {},+ "prompts": {+ "listChanged": true+ },+ "resources": {+ "subscribe": true,+ "listChanged": true+ },+ "tools": {+ "listChanged": true+ }+ },+ "serverInfo": {+ "name": "ExampleServer",+ "version": "1.0.0"+ }+ }+}+```++After successful initialization, the client **MUST** send an `initialized` notification+to indicate it is ready to begin normal operations:++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/initialized"+}+```++- The client **SHOULD NOT** send requests other than+ [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) before the server+ has responded to the `initialize` request.+- The server **SHOULD NOT** send requests other than+ [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) and+ [logging]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) before+ receiving the `initialized` notification.++#### Version Negotiation++In the `initialize` request, the client **MUST** send a protocol version it supports.+This **SHOULD** be the _latest_ version supported by the client.++If the server supports the requested protocol version, it **MUST** respond with the same+version. Otherwise, the server **MUST** respond with another protocol version it+supports. This **SHOULD** be the _latest_ version supported by the server.++If the client does not support the version in the server's response, it **SHOULD**+disconnect.++#### Capability Negotiation++Client and server capabilities establish which optional protocol features will be+available during the session.++Key capabilities include:++| Category | Capability | Description |+| -------- | -------------- | ------------------------------------------------------------------------------------------------- |+| Client | `roots` | Ability to provide filesystem [roots]({{< ref "/specification/2024-11-05/client/roots" >}}) |+| Client | `sampling` | Support for LLM [sampling]({{< ref "/specification/2024-11-05/client/sampling" >}}) requests |+| Client | `experimental` | Describes support for non-standard experimental features |+| Server | `prompts` | Offers [prompt templates]({{< ref "/specification/2024-11-05/server/prompts" >}}) |+| Server | `resources` | Provides readable [resources]({{< ref "/specification/2024-11-05/server/resources" >}}) |+| Server | `tools` | Exposes callable [tools]({{< ref "/specification/2024-11-05/server/tools" >}}) |+| Server | `logging` | Emits structured [log messages]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) |+| Server | `experimental` | Describes support for non-standard experimental features |++Capability objects can describe sub-capabilities like:++- `listChanged`: Support for list change notifications (for prompts, resources, and+ tools)+- `subscribe`: Support for subscribing to individual items' changes (resources only)++### Operation++During the operation phase, the client and server exchange messages according to the+negotiated capabilities.++Both parties **SHOULD**:++- Respect the negotiated protocol version+- Only use capabilities that were successfully negotiated++### Shutdown++During the shutdown phase, one side (usually the client) cleanly terminates the protocol+connection. No specific shutdown messages are defined—instead, the underlying transport+mechanism should be used to signal connection termination:++#### stdio++For the stdio [transport]({{< ref "/specification/2024-11-05/basic/transports" >}}), the+client **SHOULD** initiate shutdown by:++1. First, closing the input stream to the child process (the server)+2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit+ within a reasonable time+3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`++The server **MAY** initiate shutdown by closing its output stream to the client and+exiting.++#### HTTP++For HTTP [transports]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown+is indicated by closing the associated HTTP connection(s).++## Error Handling++Implementations **SHOULD** be prepared to handle these error cases:++- Protocol version mismatch+- Failure to negotiate required capabilities+- Initialize request timeout+- Shutdown timeout++Implementations **SHOULD** implement appropriate timeouts for all requests, to prevent+hung connections and resource exhaustion.++Example initialization error:++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "error": {+ "code": -32602,+ "message": "Unsupported protocol version",+ "data": {+ "supported": ["2024-11-05"],+ "requested": "1.0.0"+ }+ }+}+```++++---+File: /docs/specification/2024-11-05/basic/messages.md+---++---+title: Messages+type: docs+weight: 20+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++All messages in MCP **MUST** follow the+[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines+three types of messages:++## Requests++Requests are sent from the client to the server or vice versa.++```typescript+{+ jsonrpc: "2.0";+ id: string | number;+ method: string;+ params?: {+ [key: string]: unknown;+ };+}+```++- Requests **MUST** include a string or integer ID.+- Unlike base JSON-RPC, the ID **MUST NOT** be `null`.+- The request ID **MUST NOT** have been previously used by the requestor within the same+ session.++## Responses++Responses are sent in reply to requests.++```typescript+{+ jsonrpc: "2.0";+ id: string | number;+ result?: {+ [key: string]: unknown;+ }+ error?: {+ code: number;+ message: string;+ data?: unknown;+ }+}+```++- Responses **MUST** include the same ID as the request they correspond to.+- Either a `result` or an `error` **MUST** be set. A response **MUST NOT** set both.+- Error codes **MUST** be integers.++## Notifications++Notifications are sent from the client to the server or vice versa. They do not expect a+response.++```typescript+{+ jsonrpc: "2.0";+ method: string;+ params?: {+ [key: string]: unknown;+ };+}+```++- Notifications **MUST NOT** include an ID.++++---+File: /docs/specification/2024-11-05/basic/transports.md+---++---+title: Transports+type: docs+weight: 40+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++MCP currently defines two standard transport mechanisms for client-server communication:++1. [stdio](#stdio), communication over standard in and standard out+2. [HTTP with Server-Sent Events](#http-with-sse) (SSE)++Clients **SHOULD** support stdio whenever possible.++It is also possible for clients and servers to implement+[custom transports](#custom-transports) in a pluggable fashion.++## stdio++In the **stdio** transport:++- The client launches the MCP server as a subprocess.+- The server receives JSON-RPC messages on its standard input (`stdin`) and writes+ responses to its standard output (`stdout`).+- Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.+- The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging+ purposes. Clients **MAY** capture, forward, or ignore this logging.+- The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.+- The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP+ message.++```mermaid+sequenceDiagram+ participant Client+ participant Server Process++ Client->>+Server Process: Launch subprocess+ loop Message Exchange+ Client->>Server Process: Write to stdin+ Server Process->>Client: Write to stdout+ Server Process--)Client: Optional logs on stderr+ end+ Client->>Server Process: Close stdin, terminate subprocess+ deactivate Server Process+```++## HTTP with SSE++In the **SSE** transport, the server operates as an independent process that can handle+multiple client connections.++The server **MUST** provide two endpoints:++1. An SSE endpoint, for clients to establish a connection and receive messages from the+ server+2. A regular HTTP POST endpoint for clients to send messages to the server++When a client connects, the server **MUST** send an `endpoint` event containing a URI for+the client to use for sending messages. All subsequent client messages **MUST** be sent+as HTTP POST requests to this endpoint.++Server messages are sent as SSE `message` events, with the message content encoded as+JSON in the event data.++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Client->>Server: Open SSE connection+ Server->>Client: endpoint event+ loop Message Exchange+ Client->>Server: HTTP POST messages+ Server->>Client: SSE message events+ end+ Client->>Server: Close SSE connection+```++## Custom Transports++Clients and servers **MAY** implement additional custom transport mechanisms to suit+their specific needs. The protocol is transport-agnostic and can be implemented over any+communication channel that supports bidirectional message exchange.++Implementers who choose to support custom transports **MUST** ensure they preserve the+JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports+**SHOULD** document their specific connection establishment and message exchange patterns+to aid interoperability.++++---+File: /docs/specification/2024-11-05/client/_index.md+---++---+title: Client Features+cascade:+ type: docs+weight: 4+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++Clients can implement additional features to enrich connected MCP servers:++{{< cards >}} {{< card link="roots" title="Roots" icon="folder" >}}+{{< card link="sampling" title="Sampling" icon="annotation" >}} {{< /cards >}}++++---+File: /docs/specification/2024-11-05/client/roots.md+---++---+title: Roots+type: docs+weight: 40+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) provides a standardized way for clients to expose+filesystem "roots" to servers. Roots define the boundaries of where servers can operate+within the filesystem, allowing them to understand which directories and files they have+access to. Servers can request the list of roots from supporting clients and receive+notifications when that list changes.++## User Interaction Model++Roots in MCP are typically exposed through workspace or project configuration interfaces.++For example, implementations could offer a workspace/project picker that allows users to+select directories and files the server should have access to. This can be combined with+automatic workspace detection from version control systems or project files.++However, implementations are free to expose roots through any interface pattern that+suits their needs—the protocol itself does not mandate any specific user+interaction model.++## Capabilities++Clients that support roots **MUST** declare the `roots` capability during+[initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):++```json+{+ "capabilities": {+ "roots": {+ "listChanged": true+ }+ }+}+```++`listChanged` indicates whether the client will emit notifications when the list of roots+changes.++## Protocol Messages++### Listing Roots++To retrieve roots, servers send a `roots/list` request:++**Request:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "roots/list"+}+```++**Response:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "roots": [+ {+ "uri": "file:///home/user/projects/myproject",+ "name": "My Project"+ }+ ]+ }+}+```++### Root List Changes++When roots change, clients that support `listChanged` **MUST** send a notification:++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/roots/list_changed"+}+```++## Message Flow++```mermaid+sequenceDiagram+ participant Server+ participant Client++ Note over Server,Client: Discovery+ Server->>Client: roots/list+ Client-->>Server: Available roots++ Note over Server,Client: Changes+ Client--)Server: notifications/roots/list_changed+ Server->>Client: roots/list+ Client-->>Server: Updated roots+```++## Data Types++### Root++A root definition includes:++- `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current+ specification.+- `name`: Optional human-readable name for display purposes.++Example roots for different use cases:++#### Project Directory++```json+{+ "uri": "file:///home/user/projects/myproject",+ "name": "My Project"+}+```++#### Multiple Repositories++```json+[+ {+ "uri": "file:///home/user/repos/frontend",+ "name": "Frontend Repository"+ },+ {+ "uri": "file:///home/user/repos/backend",+ "name": "Backend Repository"+ }+]+```++## Error Handling++Clients **SHOULD** return standard JSON-RPC errors for common failure cases:++- Client does not support roots: `-32601` (Method not found)+- Internal errors: `-32603`++Example error:++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "error": {+ "code": -32601,+ "message": "Roots not supported",+ "data": {+ "reason": "Client does not have roots capability"+ }+ }+}+```++## Security Considerations++1. Clients **MUST**:++ - Only expose roots with appropriate permissions+ - Validate all root URIs to prevent path traversal+ - Implement proper access controls+ - Monitor root accessibility++2. Servers **SHOULD**:+ - Handle cases where roots become unavailable+ - Respect root boundaries during operations+ - Validate all paths against provided roots++## Implementation Guidelines++1. Clients **SHOULD**:++ - Prompt users for consent before exposing roots to servers+ - Provide clear user interfaces for root management+ - Validate root accessibility before exposing+ - Monitor for root changes++2. Servers **SHOULD**:+ - Check for roots capability before usage+ - Handle root list changes gracefully+ - Respect root boundaries in operations+ - Cache root information appropriately++++---+File: /docs/specification/2024-11-05/client/sampling.md+---++---+title: Sampling+type: docs+weight: 40+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) provides a standardized way for servers to request LLM+sampling ("completions" or "generations") from language models via clients. This flow+allows clients to maintain control over model access, selection, and permissions while+enabling servers to leverage AI capabilities—with no server API keys necessary.+Servers can request text or image-based interactions and optionally include context from+MCP servers in their prompts.++## User Interaction Model++Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to+occur _nested_ inside other MCP server features.++Implementations are free to expose sampling through any interface pattern that suits+their needs—the protocol itself does not mandate any specific user interaction+model.++{{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always+be a human in the loop with the ability to deny sampling requests.++Applications **SHOULD**:++- Provide UI that makes it easy and intuitive to review sampling requests+- Allow users to view and edit prompts before sending+- Present generated responses for review before delivery {{< /callout >}}++## Capabilities++Clients that support sampling **MUST** declare the `sampling` capability during+[initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):++```json+{+ "capabilities": {+ "sampling": {}+ }+}+```++## Protocol Messages++### Creating Messages++To request a language model generation, servers send a `sampling/createMessage` request:++**Request:**++```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:**++```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"+ }+}+```++## Message Flow++```mermaid+sequenceDiagram+ participant Server+ participant Client+ participant User+ participant LLM++ Note over Server,Client: Server initiates sampling+ Server->>Client: sampling/createMessage++ Note over Client,User: Human-in-the-loop review+ Client->>User: Present request for approval+ User-->>Client: Review and approve/modify++ Note over Client,LLM: Model interaction+ Client->>LLM: Forward approved request+ LLM-->>Client: Return generation++ Note over Client,User: Response review+ Client->>User: Present response for approval+ User-->>Client: Review and approve/modify++ Note over Server,Client: Complete request+ Client-->>Server: Return approved response+```++## Data Types++### Messages++Sampling messages can contain:++#### Text Content++```json+{+ "type": "text",+ "text": "The message content"+}+```++#### Image Content++```json+{+ "type": "image",+ "data": "base64-encoded-image-data",+ "mimeType": "image/jpeg"+}+```++### Model Preferences++Model selection in MCP requires careful abstraction since servers and clients may use+different AI providers with distinct model offerings. A server cannot simply request a+specific model by name since the client may not have access to that exact model or may+prefer to use a different provider's equivalent model.++To solve this, MCP implements a preference system that combines abstract capability+priorities with optional model hints:++#### Capability Priorities++Servers express their needs through three normalized priority values (0-1):++- `costPriority`: How important is minimizing costs? Higher values prefer cheaper models.+- `speedPriority`: How important is low latency? Higher values prefer faster models.+- `intelligencePriority`: How important are advanced capabilities? Higher values prefer+ more capable models.++#### Model Hints++While priorities help select models based on characteristics, `hints` allow servers to+suggest specific models or model families:++- Hints are treated as substrings that can match model names flexibly+- Multiple hints are evaluated in order of preference+- Clients **MAY** map hints to equivalent models from different providers+- Hints are advisory—clients make final model selection++For example:++```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+}+```++The client processes these preferences to select an appropriate model from its available+options. For instance, if the client doesn't have access to Claude models but has Gemini,+it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities.++## Error Handling++Clients **SHOULD** return errors for common failure cases:++Example error:++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "error": {+ "code": -1,+ "message": "User rejected sampling request"+ }+}+```++## Security Considerations++1. Clients **SHOULD** implement user approval controls+2. Both parties **SHOULD** validate message content+3. Clients **SHOULD** respect model preference hints+4. Clients **SHOULD** implement rate limiting+5. Both parties **MUST** handle sensitive data appropriately++++---+File: /docs/specification/2024-11-05/server/utilities/_index.md+---++---+title: Utilities+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++These optional features can be used to enhance server functionality.++{{< cards >}} {{< card link="completion" title="Completion" icon="at-symbol" >}}+{{< card link="logging" title="Logging" icon="terminal" >}}+{{< card link="pagination" title="Pagination" icon="collection" >}} {{< /cards >}}++++---+File: /docs/specification/2024-11-05/server/utilities/completion.md+---++---+title: Completion+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) provides a standardized way for servers to offer+argument autocompletion suggestions for prompts and resource URIs. This enables rich,+IDE-like experiences where users receive contextual suggestions while entering argument+values.++## User Interaction Model++Completion in MCP is designed to support interactive user experiences similar to IDE code+completion.++For example, applications may show completion suggestions in a dropdown or popup menu as+users type, with the ability to filter and select from available options.++However, implementations are free to expose completion through any interface pattern that+suits their needs—the protocol itself does not mandate any specific user+interaction model.++## Protocol Messages++### Requesting Completions++To get completion suggestions, clients send a `completion/complete` request specifying+what is being completed through a reference type:++**Request:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "completion/complete",+ "params": {+ "ref": {+ "type": "ref/prompt",+ "name": "code_review"+ },+ "argument": {+ "name": "language",+ "value": "py"+ }+ }+}+```++**Response:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "completion": {+ "values": ["python", "pytorch", "pyside"],+ "total": 10,+ "hasMore": true+ }+ }+}+```++### Reference Types++The protocol supports two types of completion references:++| Type | Description | Example |+| -------------- | --------------------------- | --------------------------------------------------- |+| `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` |+| `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` |++### Completion Results++Servers return an array of completion values ranked by relevance, with:++- Maximum 100 items per response+- Optional total number of available matches+- Boolean indicating if additional results exist++## Message Flow++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Note over Client: User types argument+ Client->>Server: completion/complete+ Server-->>Client: Completion suggestions++ Note over Client: User continues typing+ Client->>Server: completion/complete+ Server-->>Client: Refined suggestions+```++## Data Types++### CompleteRequest++- `ref`: A `PromptReference` or `ResourceReference`+- `argument`: Object containing:+ - `name`: Argument name+ - `value`: Current value++### CompleteResult++- `completion`: Object containing:+ - `values`: Array of suggestions (max 100)+ - `total`: Optional total matches+ - `hasMore`: Additional results flag++## Implementation Considerations++1. Servers **SHOULD**:++ - Return suggestions sorted by relevance+ - Implement fuzzy matching where appropriate+ - Rate limit completion requests+ - Validate all inputs++2. Clients **SHOULD**:+ - Debounce rapid completion requests+ - Cache completion results where appropriate+ - Handle missing or partial results gracefully++## Security++Implementations **MUST**:++- Validate all completion inputs+- Implement appropriate rate limiting+- Control access to sensitive suggestions+- Prevent completion-based information disclosure++++---+File: /docs/specification/2024-11-05/server/utilities/logging.md+---++---+title: Logging+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) provides a standardized way for servers to send+structured log messages to clients. Clients can control logging verbosity by setting+minimum log levels, with servers sending notifications containing severity levels,+optional logger names, and arbitrary JSON-serializable data.++## User Interaction Model++Implementations are free to expose logging through any interface pattern that suits their+needs—the protocol itself does not mandate any specific user interaction model.++## Capabilities++Servers that emit log message notifications **MUST** declare the `logging` capability:++```json+{+ "capabilities": {+ "logging": {}+ }+}+```++## Log Levels++The protocol follows the standard syslog severity levels specified in+[RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1):++| Level | Description | Example Use Case |+| --------- | -------------------------------- | -------------------------- |+| debug | Detailed debugging information | Function entry/exit points |+| info | General informational messages | Operation progress updates |+| notice | Normal but significant events | Configuration changes |+| warning | Warning conditions | Deprecated feature usage |+| error | Error conditions | Operation failures |+| critical | Critical conditions | System component failures |+| alert | Action must be taken immediately | Data corruption detected |+| emergency | System is unusable | Complete system failure |++## Protocol Messages++### Setting Log Level++To configure the minimum log level, clients **MAY** send a `logging/setLevel` request:++**Request:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "logging/setLevel",+ "params": {+ "level": "info"+ }+}+```++### Log Message Notifications++Servers send log messages using `notifications/message` notifications:++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/message",+ "params": {+ "level": "error",+ "logger": "database",+ "data": {+ "error": "Connection failed",+ "details": {+ "host": "localhost",+ "port": 5432+ }+ }+ }+}+```++## Message Flow++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Note over Client,Server: Configure Logging+ Client->>Server: logging/setLevel (info)+ Server-->>Client: Empty Result++ Note over Client,Server: Server Activity+ Server--)Client: notifications/message (info)+ Server--)Client: notifications/message (warning)+ Server--)Client: notifications/message (error)++ Note over Client,Server: Level Change+ Client->>Server: logging/setLevel (error)+ Server-->>Client: Empty Result+ Note over Server: Only sends error level<br/>and above+```++## Error Handling++Servers **SHOULD** return standard JSON-RPC errors for common failure cases:++- Invalid log level: `-32602` (Invalid params)+- Configuration errors: `-32603` (Internal error)++## Implementation Considerations++1. Servers **SHOULD**:++ - Rate limit log messages+ - Include relevant context in data field+ - Use consistent logger names+ - Remove sensitive information++2. Clients **MAY**:+ - Present log messages in the UI+ - Implement log filtering/search+ - Display severity visually+ - Persist log messages++## Security++1. Log messages **MUST NOT** contain:++ - Credentials or secrets+ - Personal identifying information+ - Internal system details that could aid attacks++2. Implementations **SHOULD**:+ - Rate limit messages+ - Validate all data fields+ - Control log access+ - Monitor for sensitive content++++---+File: /docs/specification/2024-11-05/server/utilities/pagination.md+---++---+title: Pagination+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) supports paginating list operations that may return+large result sets. Pagination allows servers to yield results in smaller chunks rather+than all at once.++Pagination is especially important when connecting to external services over the+internet, but also useful for local integrations to avoid performance issues with large+data sets.++## Pagination Model++Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.++- The **cursor** is an opaque string token, representing a position in the result set+- **Page size** is determined by the server, and **MAY NOT** be fixed++## Response Format++Pagination starts when the server sends a **response** that includes:++- The current page of results+- An optional `nextCursor` field if more results exist++```json+{+ "jsonrpc": "2.0",+ "id": "123",+ "result": {+ "resources": [...],+ "nextCursor": "eyJwYWdlIjogM30="+ }+}+```++## Request Format++After receiving a cursor, the client can _continue_ paginating by issuing a request+including that cursor:++```json+{+ "jsonrpc": "2.0",+ "method": "resources/list",+ "params": {+ "cursor": "eyJwYWdlIjogMn0="+ }+}+```++## Pagination Flow++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Client->>Server: List Request (no cursor)+ loop Pagination Loop+ Server-->>Client: Page of results + nextCursor+ Client->>Server: List Request (with cursor)+ end+```++## Operations Supporting Pagination++The following MCP operations support pagination:++- `resources/list` - List available resources+- `resources/templates/list` - List resource templates+- `prompts/list` - List available prompts+- `tools/list` - List available tools++## Implementation Guidelines++1. Servers **SHOULD**:++ - Provide stable cursors+ - Handle invalid cursors gracefully++2. Clients **SHOULD**:++ - Treat a missing `nextCursor` as the end of results+ - Support both paginated and non-paginated flows++3. Clients **MUST** treat cursors as opaque tokens:+ - Don't make assumptions about cursor format+ - Don't attempt to parse or modify cursors+ - Don't persist cursors across sessions++## Error Handling++Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params).++++---+File: /docs/specification/2024-11-05/server/_index.md+---++---+title: Server Features+cascade:+ type: docs+weight: 3+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++Servers provide the fundamental building blocks for adding context to language models via+MCP. These primitives enable rich interactions between clients, servers, and language+models:++- **Prompts**: Pre-defined templates or instructions that guide language model+ interactions+- **Resources**: Structured data or content that provides additional context to the model+- **Tools**: Executable functions that allow models to perform actions or retrieve+ information++Each primitive can be summarized in the following control hierarchy:++| Primitive | Control | Description | Example |+| --------- | ---------------------- | -------------------------------------------------- | ------------------------------- |+| Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |+| Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |+| Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |++Explore these key primitives in more detail below:++{{< cards >}} {{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}+{{< card link="resources" title="Resources" icon="document" >}}+{{< card link="tools" title="Tools" icon="adjustments" >}} {{< /cards >}}++++---+File: /docs/specification/2024-11-05/server/prompts.md+---++---+title: Prompts+weight: 10+---++{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}++The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt+templates to clients. Prompts allow servers to provide structured messages and+instructions for interacting with language models. Clients can discover available+prompts, retrieve their contents, and provide arguments to customize them.++## User Interaction Model++Prompts are designed to be **user-controlled**, meaning they are exposed from servers to+clients with the intention of the user being able to explicitly select them for use.++Typically, prompts would be triggered through user-initiated commands in the user+interface, which allows users to naturally discover and invoke available prompts.++For example, as slash commands:++++However, implementors are free to expose prompts through any interface pattern that suits+their needs—the protocol itself does not mandate any specific user interaction+model.++## Capabilities++Servers that support prompts **MUST** declare the `prompts` capability during+[initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):++```json+{+ "capabilities": {+ "prompts": {+ "listChanged": true+ }+ }+}+```++`listChanged` indicates whether the server will emit notifications when the list of+available prompts changes.++## Protocol Messages++### Listing Prompts++To retrieve available prompts, clients send a `prompts/list` request. This operation+supports+[pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).++**Request:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "method": "prompts/list",+ "params": {+ "cursor": "optional-cursor-value"+ }+}+```++**Response:**++```json+{+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "prompts": [+ {+ "name": "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"+ }+}+```++### Getting a Prompt++To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be+auto-completed through [the completion+API]({{< ref "/specification/2024-11-05/server/utilities/completion" >}}).++**Request:**++```json+{+ "jsonrpc": "2.0",+ "id": 2,+ "method": "prompts/get",+ "params": {+ "name": "code_review",+ "arguments": {+ "code": "def hello():\n print('world')"+ }+ }+}+```++**Response:**++```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')"+ }+ }+ ]+ }+}+```++### List Changed Notification++When the list of available prompts changes, servers that declared the `listChanged`+capability **SHOULD** send a notification:++```json+{+ "jsonrpc": "2.0",+ "method": "notifications/prompts/list_changed"+}+```++## Message Flow++```mermaid+sequenceDiagram+ participant Client+ participant Server++ Note over Client,Server: Discovery+ Client->>Server: prompts/list+ Server-->>Client: List of prompts++ Note over Client,Server: Usage+ Client->>Server: prompts/get+ Server-->>Client: Prompt content++ opt listChanged+ Note over Client,Server: Changes+ Server--)Client: prompts/list_changed+ Client->>Server: prompts/list+ Server-->>Client: Updated prompts+ end+```++## Data Types++### Prompt++A prompt definition includes:++- `name`: Unique identifier for the prompt+- `description`: Optional human-readable description+- `arguments`: Optional list of arguments for customization++### PromptMessage++Messages in a prompt can contain:++- `role`: Either "user" or "assistant" to indicate the speaker+- `content`: One of the following content types:++#### Text Content++Text content represents plain text messages:++```json+{+ "type": "text",+ "text": "The text content of the message"+}+```++This is the most common content type used for natural language interactions.++#### Image Content++Image content allows including visual information in messages:++```json+{+ "type": "image",+ "data": "base64-encoded-image-data",+ "mimeType": "image/png"+}+```++The image data **MUST** be base64-encoded and include a valid MIME type. This enables+multi-modal interactions where visual context is important.++#### Embedded Resources++Embedded resources allow referencing server-side resources directly in messages:++```json+{+ "type": "resource",+ "resource": {+ "uri": "resource://example",+ "mimeType": "text/plain",+ "text": "Resource content"+ }+}+```++Resources can contain either text or binary (blob) data and **MUST** include:++- A valid resource URI+- The appropriate MIME type+- Either text content or base64-encoded blob data++Embedded resources enable prompts to seamlessly incorporate server-managed content like+documentation, code samples, or other reference materials directly into the conversation+flow.++## Error Handling++Servers **SHOULD** return standard JSON-RPC errors for common failure cases:++- Invalid prompt name: `-32602` (Invalid params)+- Missing required arguments: `-32602` (Invalid params)+- Internal errors: `-32603` (Internal error)++## Implementation Considerations++1. Servers **SHOULD** validate prompt arguments before processing+2. Clients **SHOULD** handle pagination for large prompt lists+3. Both parties **SHOULD** respect capability negotiation++## Security++Implementations **MUST** carefully validate all prompt inputs and outputs to prevent+injection attacks or unauthorized access to resources.++++---+File: /docs/specification/2024-11-05/server/resource-picker.png+---++�PNG+++IHDR � � �Ķ `iCCPICC Profile (�u�;HA��h$D��H!Q�*���rF,� XQ��K��d�w������6bci��B҉��"��B4���z�������0��3� �%�g� ium]�!+?n���.P �����z7&fͤcR�rp68$o��?����x�����~P�t�m���;6|H��`����-�5k�2I�{�^�r��đl�o�q��ֿv���E�0�0R�ä��+�P ӟ"�?}J�/�2����� �¤��Q��qD�eLR*���zG������%P��7z\7L���u=u���[�@ϛ㼎 �K�����q�@�#P�|.La�vY' beXIfMM * �i &