From 8d0a93d829c3205aa76071c41ead0fe2449d052d Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 12:19:50 +0000 Subject: [PATCH 01/33] Update _index.md --- docs/specification/_index.md | 48 ++++++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/specification/_index.md b/docs/specification/_index.md index 7d799e2..c2cb94a 100644 --- a/docs/specification/_index.md +++ b/docs/specification/_index.md @@ -10,7 +10,11 @@ weight: 10 **Protocol Revision**: 2024-11-05 {{< /callout >}} -The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. This specification defines the authoritative protocol requirements based on the TypeScript schema in [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/schema.ts). For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io). +[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. + +This specification defines the authoritative protocol requirements, based on the TypeScript schema in [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/schema.ts). + +For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io). ## Overview @@ -20,32 +24,40 @@ MCP provides a standardized way for applications to: - Expose tools and capabilities to AI systems - Build composable integrations and workflows -The protocol uses JSON-RPC 2.0 messages to establish communication between: +The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish communication between: -- **Clients**: Applications that integrate with language models +- **Hosts**: LLM applications that initiate connections +- **Clients**: Connectors within the host application - **Servers**: Services that provide context and capabilities -- **Hosts**: Processes that manage client connections -## Core Protocol Features +MCP takes some inspiration from the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which standardizes how to add support for programming languages across a whole ecosystem of development tools. In a similar way, MCP standardizes how to integrate additional context and tools into the ecosystem of AI applications. -MCP defines several key components: +## Key Details ### Base Protocol -- JSON-RPC message format -- Capability negotiation -- Session lifecycle management +- [JSON-RPC](https://www.jsonrpc.org/) message format +- Stateful connections +- Server and client capability negotiation + +### Features + +Servers offer any of the following features to clients: + +- **Resources**: Context and data, for the user or the AI model to use +- **Prompts**: Templated messages and workflows for users +- **Tools**: Functions for the AI model to execute + +Clients may offer the following feature to servers: + +- **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions -### Context Primitives -- **Resources**: Data exposed via URIs -- **Prompts**: Template-based interactions -- **Tools**: Executable functions -- **Sampling**: LLM generation control +### Additional Utilities -### Cross-Cutting Concerns +- Configuration - Progress tracking -- Error handling -- Security boundaries -- Backwards compatibility +- Cancellation +- Error reporting +- Logging ## Learn More From 9f4f47f38ce329c255fad0c0f3feb1b77b89272e Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:01:34 +0000 Subject: [PATCH 02/33] Update architecture page --- docs/specification/architecture/_index.md | 103 ++++++++++------------ 1 file changed, 48 insertions(+), 55 deletions(-) diff --git a/docs/specification/architecture/_index.md b/docs/specification/architecture/_index.md index 1e32eb2..a0edbb2 100644 --- a/docs/specification/architecture/_index.md +++ b/docs/specification/architecture/_index.md @@ -10,7 +10,7 @@ The Model Context Protocol (MCP) follows a client-host-server architecture where ## Core Components ```mermaid -graph TB +graph LR subgraph "Application Host Process" H[Host] C1[Client 1] @@ -20,21 +20,26 @@ graph TB H --> C2 H --> C3 end - S1[Server 1
Files & Git] - S2[Server 2
Database] - S3[Server 3
External APIs] - R1[("Local
Resource A")] - R2[("Local
Resource B")] - R3[("Local
Resource C")] + subgraph "Local machine" + S1[Server 1
Files & Git] + S2[Server 2
Database] + R1[("Local
Resource A")] + R2[("Local
Resource B")] - C1 --> S1 - C2 --> S2 - C3 --> S3 + C1 --> S1 + C2 --> S2 + S1 <--> R1 + S2 <--> R2 + end + + subgraph "Internet" + S3[Server 3
External APIs] + R3[("Remote
Resource C")] - S1 <--> R1 - S2 <--> R2 - S3 <--> R3 + C3 --> S3 + S3 <--> R3 + end ``` ### Host @@ -62,14 +67,23 @@ Servers provide specialized context and capabilities: - Must respect security constraints - Can be local processes or remote services -## Protocol Capabilities and Flow +## 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 protocol extensions +- Additional capabilities can be negotiated through extensions to the protocol ```mermaid sequenceDiagram @@ -77,61 +91,40 @@ sequenceDiagram participant Client participant Server - Host->>Client: Initialize client - Client->>Server: Initialize session with capabilities - Server-->>Client: Negotiate supported capabilities + 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 - alt Server Request (if sampling capable) + 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 - else Client Request (based on server caps) - Client->>Server: Request (tools/resources) - Server-->>Client: Response - else Notifications (if supported) + end + + loop Notifications Server--)Client: Resource updates Client--)Server: Status changes end Host->>Client: Terminate - Client->>Server: End session + Client->>-Server: End session + deactivate Server ``` Each capability unlocks specific protocol features for use during the session. For example: -- Resource subscriptions require the server to declare subscription support +- Implemented [server features]({{< ref "/specification/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 requires the client to declare sampling support +- [Sampling]({{< ref "/specification/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. - -### 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**: 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. - -## Protocol Features - -### Server Features -Servers implement several foundational features that provide context and capabilities to clients: - -- **Resources**: Structured data or content exposed via URIs that can be read and optionally subscribed to for updates -- **Prompts**: Pre-defined templates or instructions that guide language model interactions -- **Tools**: Executable functions that allow models to perform actions or retrieve information -- **Utilities**: Helper features for logging, argument completion, and other ancillary functions - -The server features focus on exposing data and functionality in a controlled way while maintaining security boundaries. - -### Client Features -Clients provide core features for interacting with servers and coordinating with hosts: - -- **Sampling**: Ability to request and control language model interactions -- **Root Directory Access**: Controlled exposure of filesystem locations to servers - -The client features emphasize safe integration of server capabilities while protecting user privacy and security. From 7ceb3086da177456f6e063a0c81f2ba6c56f2579 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:17:55 +0000 Subject: [PATCH 03/33] Update "base protocol" --- docs/specification/basic/_index.md | 38 ++++++++++++++++-------------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/specification/basic/_index.md b/docs/specification/basic/_index.md index 230950e..762ff31 100644 --- a/docs/specification/basic/_index.md +++ b/docs/specification/basic/_index.md @@ -5,33 +5,31 @@ cascade: weight: 2 --- -The Model Context Protocol (MCP) defines a set of JSON-RPC methods for communication between clients and servers in AI-assisted applications. MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) as its base protocol. +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: -All messages in MCP **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 | -| 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. -The Model Context Protocol consists of several key components that work together: +## Protocol Layers -**Protocol Layers:** +The Model Context Protocol consists of several key components that work together: -- **Base Protocol**: Core JSON-RPC message types and fundamental operations such as capability exchange +- **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 capabilities +- **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. -### Model Context Protocol specific methods - -MCP defines methods based on JSON-RPC that clients and servers implement: +See the following pages for more details on the different components: {{< cards >}} {{< card link="lifecycle" title="Lifecycle" icon="refresh" >}} @@ -42,10 +40,14 @@ MCP defines methods based on JSON-RPC that clients and servers implement: {{< card link="sampling" title="Sampling" icon="code" >}} {{< /cards >}} -### Authentication +## 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. -Authentication mechanisms are not part of the core MCP specification. Implementations **MAY** provide authentication based on the transport they use. +## Schema -## Specification +The full specification of the protocol is defined as a [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts). This is the source of truth for all protocol messages and structures. -The official specification can be found in [TypeScript source](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts) and [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json) formats. The TypeScript version serves as the source of truth, while the JSON Schema version is generated from it. +There is also a [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json), which is automatically generated from the TypeScript source of truth, for use with various automated tooling. From d632f0398db9dc92cc21ff77487ba84a8d3223c8 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:20:09 +0000 Subject: [PATCH 04/33] Fix card links --- docs/specification/basic/_index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/specification/basic/_index.md b/docs/specification/basic/_index.md index 762ff31..3fb93c5 100644 --- a/docs/specification/basic/_index.md +++ b/docs/specification/basic/_index.md @@ -32,12 +32,12 @@ These protocol layers establish clear separation of concerns while enabling rich See the following pages for more details on the different components: {{< cards >}} - {{< card link="lifecycle" title="Lifecycle" icon="refresh" >}} - {{< card link="resources" title="Resources" icon="document" >}} - {{< card link="prompts" title="Prompts" icon="chat-alt-2" >}} - {{< card link="tools" title="Tools" icon="adjustments" >}} - {{< card link="logging" title="Logging" icon="annotation" >}} - {{< card link="sampling" title="Sampling" icon="code" >}} + {{< card link="/specification/basic/lifecycle" title="Lifecycle" icon="refresh" >}} + {{< card link="/specification/server/resources" title="Resources" icon="document" >}} + {{< card link="/specification/server/prompts" title="Prompts" icon="chat-alt-2" >}} + {{< card link="/specification/server/tools" title="Tools" icon="adjustments" >}} + {{< card link="/specification/server/utilities/logging" title="Logging" icon="annotation" >}} + {{< card link="/specification/client/sampling" title="Sampling" icon="code" >}} {{< /cards >}} ## Auth From 2a4a67645322bf9f4d5c7c6b06294062b70d0036 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:26:06 +0000 Subject: [PATCH 05/33] Use a param for the latest protocol revision --- docs/specification/_index.md | 2 +- docs/specification/basic/lifecycle.md | 2 +- docs/specification/basic/messages.md | 2 +- docs/specification/basic/transports.md | 2 +- docs/specification/basic/utilities/cancellation.md | 2 +- docs/specification/basic/utilities/pagination.md | 2 +- docs/specification/basic/utilities/ping.md | 2 +- docs/specification/basic/utilities/progress.md | 2 +- docs/specification/basic/versioning.md | 2 +- docs/specification/client/roots.md | 2 +- docs/specification/client/sampling.md | 2 +- docs/specification/server/prompts.md | 2 +- docs/specification/server/resources.md | 2 +- docs/specification/server/tools.md | 2 +- docs/specification/server/utilities/completion.md | 2 +- docs/specification/server/utilities/logging.md | 2 +- site/hugo.yaml | 4 +--- 17 files changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/specification/_index.md b/docs/specification/_index.md index c2cb94a..be58725 100644 --- a/docs/specification/_index.md +++ b/docs/specification/_index.md @@ -7,7 +7,7 @@ weight: 10 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. diff --git a/docs/specification/basic/lifecycle.md b/docs/specification/basic/lifecycle.md index 0a8ca50..46b1728 100644 --- a/docs/specification/basic/lifecycle.md +++ b/docs/specification/basic/lifecycle.md @@ -5,7 +5,7 @@ weight: 30 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management. This lifecycle consists of four distinct phases: diff --git a/docs/specification/basic/messages.md b/docs/specification/basic/messages.md index 0db6fe9..a800f35 100644 --- a/docs/specification/basic/messages.md +++ b/docs/specification/basic/messages.md @@ -4,7 +4,7 @@ type: docs weight: 20 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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: diff --git a/docs/specification/basic/transports.md b/docs/specification/basic/transports.md index 30e7438..a7e6e87 100644 --- a/docs/specification/basic/transports.md +++ b/docs/specification/basic/transports.md @@ -4,7 +4,7 @@ type: docs weight: 40 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} MCP supports multiple transport mechanisms for client-server communication. The two standard transport mechanisms are STDIO and HTTP with Server-Sent Events (SSE). We recommend clients to support at least STDIO. diff --git a/docs/specification/basic/utilities/cancellation.md b/docs/specification/basic/utilities/cancellation.md index 08ab811..59a0375 100644 --- a/docs/specification/basic/utilities/cancellation.md +++ b/docs/specification/basic/utilities/cancellation.md @@ -4,7 +4,7 @@ weight: 10 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/docs/specification/basic/utilities/pagination.md b/docs/specification/basic/utilities/pagination.md index 25ca37d..2ba7369 100644 --- a/docs/specification/basic/utilities/pagination.md +++ b/docs/specification/basic/utilities/pagination.md @@ -3,7 +3,7 @@ title: Pagination weight: 20 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) supports pagination for list operations that may return large result sets. Pagination allows clients to retrieve results in smaller chunks rather than all at once. diff --git a/docs/specification/basic/utilities/ping.md b/docs/specification/basic/utilities/ping.md index 7a25473..126b7f6 100644 --- a/docs/specification/basic/utilities/ping.md +++ b/docs/specification/basic/utilities/ping.md @@ -4,7 +4,7 @@ weight: 5 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/docs/specification/basic/utilities/progress.md b/docs/specification/basic/utilities/progress.md index 139a658..3e7cb38 100644 --- a/docs/specification/basic/utilities/progress.md +++ b/docs/specification/basic/utilities/progress.md @@ -3,7 +3,7 @@ title: Progress weight: 30 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/docs/specification/basic/versioning.md b/docs/specification/basic/versioning.md index 4820f91..d7fe316 100644 --- a/docs/specification/basic/versioning.md +++ b/docs/specification/basic/versioning.md @@ -4,7 +4,7 @@ type: docs weight: 80 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol uses string-based version identifiers following the format `YYYY-MM-DD` to indicate the last date significant changes were made. The current protocol version is `2024-11-05`. diff --git a/docs/specification/client/roots.md b/docs/specification/client/roots.md index 8d2ffe9..6748e84 100644 --- a/docs/specification/client/roots.md +++ b/docs/specification/client/roots.md @@ -5,7 +5,7 @@ weight: 40 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/docs/specification/client/sampling.md b/docs/specification/client/sampling.md index 7b4c3d3..a8c46a9 100644 --- a/docs/specification/client/sampling.md +++ b/docs/specification/client/sampling.md @@ -5,7 +5,7 @@ weight: 40 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to request generations from language models via clients. This unique reverse flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities. Servers can request text or image-based interactions and optionally include context from MCP servers in their prompts. diff --git a/docs/specification/server/prompts.md b/docs/specification/server/prompts.md index 385ad09..39d82e0 100644 --- a/docs/specification/server/prompts.md +++ b/docs/specification/server/prompts.md @@ -4,7 +4,7 @@ weight: 10 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/docs/specification/server/resources.md b/docs/specification/server/resources.md index a74ba61..adfdc19 100644 --- a/docs/specification/server/resources.md +++ b/docs/specification/server/resources.md @@ -5,7 +5,7 @@ weight: 20 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to expose resources to clients. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a [URI](https://datatracker.ietf.org/doc/html/rfc3986). diff --git a/docs/specification/server/tools.md b/docs/specification/server/tools.md index 8172f5f..e79bb81 100644 --- a/docs/specification/server/tools.md +++ b/docs/specification/server/tools.md @@ -5,7 +5,7 @@ weight: 40 --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by language models through clients. Tools enable models to perform actions or retrieve information beyond their training data, such as querying databases, calling external APIs, or executing commands. Each tool is uniquely identified by a name and includes metadata describing its capabilities and requirements. diff --git a/docs/specification/server/utilities/completion.md b/docs/specification/server/utilities/completion.md index 26ef756..1b5a1c4 100644 --- a/docs/specification/server/utilities/completion.md +++ b/docs/specification/server/utilities/completion.md @@ -3,7 +3,7 @@ title: Completion --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to provide argument completion suggestions for prompts and resource URIs. This enables rich, IDE-like experiences where users receive contextual suggestions while entering argument values. diff --git a/docs/specification/server/utilities/logging.md b/docs/specification/server/utilities/logging.md index af3fae3..4e24563 100644 --- a/docs/specification/server/utilities/logging.md +++ b/docs/specification/server/utilities/logging.md @@ -3,7 +3,7 @@ title: Logging --- {{< callout type="info" >}} -**Protocol Revision**: 2024-11-05 +**Protocol Revision**: {{< param protocolRevision >}} {{< /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. diff --git a/site/hugo.yaml b/site/hugo.yaml index 3132e8a..63e83d1 100644 --- a/site/hugo.yaml +++ b/site/hugo.yaml @@ -26,9 +26,7 @@ params: link: / width: 204 height: 30 - mcp_base: "https://modelcontextprotocol.io" - github_base: "https://github.com/modelcontextprotocol" - uv_docs: "https://docs.astral.sh/uv/" + protocolRevision: "2024-11-05" markup: goldmark: From 2619af9bcb9da46db80c4e9d590751f089812a77 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:26:27 +0000 Subject: [PATCH 06/33] Fix typo in Base Protocol > Utilities --- docs/specification/basic/utilities/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/basic/utilities/_index.md b/docs/specification/basic/utilities/_index.md index bc7dc42..03a6ffa 100644 --- a/docs/specification/basic/utilities/_index.md +++ b/docs/specification/basic/utilities/_index.md @@ -1,5 +1,5 @@ --- -title: Utilties +title: Utilities --- The Model Context Protocol includes several optional features that enhance the base protocol functionality. These features can be used independently to add capabilities like request cancellation, paginated results, and progress tracking. From 1b0c5794b62b523ea7c9909c2828f91c503eb4ee Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 14:39:01 +0000 Subject: [PATCH 07/33] Update messages.md --- docs/specification/basic/messages.md | 62 +++++++++++++++++++--------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/docs/specification/basic/messages.md b/docs/specification/basic/messages.md index a800f35..3a5a2ac 100644 --- a/docs/specification/basic/messages.md +++ b/docs/specification/basic/messages.md @@ -9,38 +9,60 @@ weight: 20 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 -Requests are sent from the client to the server or vice versa. They **MUST** include a unique `id` and expect a response. +Requests are sent from the client to the server or vice versa. -### Responses - -Responses are sent in reply to requests. They **MUST** include the same `id` as the corresponding request. - -### Notifications +```typescript +{ + jsonrpc: "2.0"; + id: string | number; + method: string; + params?: { + [key: string]: unknown; + }; +} +``` -Notifications are sent from the client to the server or vice versa. They do not expect a response and **MUST NOT** include an `id`. +* 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. -### Ping Messages +## Responses -Either party can send ping messages to check if the other is still alive and responsive: +Responses are sent in reply to requests. -```json +```typescript { - "jsonrpc": "2.0", - "id": 1, - "method": "ping" + jsonrpc: "2.0"; + id: string | number; + result?: { + [key: string]: unknown; + } + error?: { + code: number; + message: string; + data?: unknown; + } } ``` -The receiver MUST respond promptly with an empty result: +* 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. -```json +```typescript { - "jsonrpc": "2.0", - "id": 1, - "result": {} + jsonrpc: "2.0"; + method: string; + params?: { + [key: string]: unknown; + }; } ``` -If the receiver fails to respond in a timely manner, the sender MAY disconnect. +* Notifications **MUST NOT** include an ID. From 6538467456ec6a3cd14da8a7d26056c3ce4ad3e4 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:03:57 +0000 Subject: [PATCH 08/33] Update lifecycle.md --- docs/specification/basic/lifecycle.md | 123 +++++++++++++++----------- 1 file changed, 70 insertions(+), 53 deletions(-) diff --git a/docs/specification/basic/lifecycle.md b/docs/specification/basic/lifecycle.md index 46b1728..f68d2ba 100644 --- a/docs/specification/basic/lifecycle.md +++ b/docs/specification/basic/lifecycle.md @@ -8,12 +8,11 @@ weight: 30 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management. This lifecycle consists of four distinct phases: +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. **Ready**: Final confirmation before beginning operations -3. **Operation**: Normal protocol communication -4. **Shutdown**: Graceful termination of the connection +2. **Operation**: Normal protocol communication +3. **Shutdown**: Graceful termination of the connection ```mermaid sequenceDiagram @@ -21,36 +20,33 @@ sequenceDiagram participant Server Note over Client,Server: Initialization Phase - Client->>Server: initialize request + activate Client + Client->>+Server: initialize request Server-->>Client: initialize response Client--)Server: initialized notification Note over Client,Server: Operation Phase - activate Client - activate Server rect rgb(200, 220, 250) note over Client,Server: Normal protocol operations end - deactivate Client - deactivate Server - Note over Client,Server: Shutdown Phase - Client->>Server: shutdown request - Server-->>Client: shutdown response + Note over Client,Server: Shutdown + Client--)-Server: Disconnect + deactivate Server Note over Client,Server: Connection closed ``` ## Lifecycle Phases -### 1. Initialization Phase +### Initialization -The initialization phase MUST be the first interaction between client and server. During this phase, the client and server: +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: +The client **MUST** initiate this phase by sending an `initialize` request containing: - Protocol version supported - Client capabilities @@ -77,7 +73,7 @@ The client MUST initiate this phase by sending an `initialize` request containin } ``` -The server MUST respond with its own capabilities and information: +The server **MUST** respond with its own capabilities and information: ```json { @@ -86,6 +82,7 @@ The server MUST respond with its own capabilities and information: "result": { "protocolVersion": "2024-11-05", "capabilities": { + "logging": {}, "prompts": { "listChanged": true }, @@ -105,28 +102,7 @@ The server MUST respond with its own capabilities and information: } ``` -#### Capability Negotiation - -The initialization phase establishes which optional protocol features will be available during the session. Key capabilities include: - -| Category | Capability | Description | -|---------------|---------------|-----------------------------------------------| -| Client | `roots` | Ability to provide filesystem roots | -| Client | `sampling` | Support for LLM sampling requests | -| Client | `experimental`| Support for non-standard experimental features| -| Server | `prompts` | Offers prompt templates | -| Server | `resources` | Provides readable resources | -| Server | `tools` | Exposes callable tools | -| Server | `logging` | Support for structured log messages | -| Server | `experimental`| Support for non-standard experimental features| - -Capabilities can include sub-capabilities like: -- `listChanged`: Support for list change notifications (for prompts, resources, and tools) -- `subscribe`: Support for subscriptions (resources only) - -### 2. Ready Phase - -After successful initialization, the client MUST send an `initialized` notification to indicate it is ready to begin normal operations: +After successful initialization, the client **MUST** send an `initialized` notification to indicate it is ready to begin normal operations: ```json { @@ -135,34 +111,75 @@ After successful initialization, the client MUST send an `initialized` notificat } ``` -The server MUST NOT send any protocol messages besides the initialization response until it receives this notification. +* The client **SHOULD NOT** send requests other than [pings]({{< ref "/specification/basic/utilities/ping" >}}) before the server has responded to the `initialize` request. +* The server **SHOULD NOT** send requests other than [pings]({{< ref "/specification/basic/utilities/ping" >}}) and [logging]({{< ref "/specification/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. -### 3. Operation Phase +#### 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/client/roots" >}}) | +| Client | `sampling` | Support for LLM [sampling]({{< ref "/specification/client/sampling" >}}) requests | +| Client | `experimental` | Describes support for non-standard experimental features | +| Server | `prompts` | Offers [prompt templates]({{< ref "/specification/server/prompts" >}}) | +| Server | `resources` | Provides readable [resources]({{< ref "/specification/server/resources" >}}) | +| Server | `tools` | Exposes callable [tools]({{< ref "/specification/server/tools" >}}) | +| Server | `logging` | Emits structured [log messages]({{< ref "/specification/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. -During the operation phase, the client and server exchange messages according to the negotiated capabilities. Both parties MUST: +Both parties **SHOULD**: - Respect the negotiated protocol version - Only use capabilities that were successfully negotiated -- Handle messages according to the JSON-RPC 2.0 specification -### 4. Shutdown Phase -The shutdown phase cleanly terminates the protocol connection. No specific shutdown messages are defined - instead, the underlying transport mechanism should be used to signal connection termination: +### Shutdown -- For STDIO-based transport, the MCP server process should be terminated -- For HTTP-based transport, the HTTP connection should be closed +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/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/basic/transports" >}}), shutdown is indicated by closing the associated HTTP connection(s). ## Error Handling -Implementations MUST handle these error cases: +Implementations **SHOULD** be prepared to handle these error cases: - Protocol version mismatch -- Required capability negotiation failure +- Failure to negotiate required capabilities - Initialize request timeout -- Shutdown request timeout - -Server implementations are SHOULD implement appropriate timeouts for all lifecycle phases to prevent hung connections and resource exhaustion. +- Shutdown timeout -When errors occur during initialization, the server MUST respond with an appropriate error code and SHOULD close the connection. +Implementations **SHOULD** implement appropriate timeouts for all requests, to prevent hung connections and resource exhaustion. Example initialization error: ```json @@ -170,7 +187,7 @@ Example initialization error: "jsonrpc": "2.0", "id": 1, "error": { - "code": -32600, + "code": -32602, "message": "Unsupported protocol version", "data": { "supported": ["2024-11-05"], From a64a9396ba2600e384ec1b843fe8244f571c9a6f Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:32:33 +0000 Subject: [PATCH 09/33] Update transports.md --- docs/specification/basic/transports.md | 47 ++++++++++++++++---------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/docs/specification/basic/transports.md b/docs/specification/basic/transports.md index a7e6e87..b749707 100644 --- a/docs/specification/basic/transports.md +++ b/docs/specification/basic/transports.md @@ -7,36 +7,47 @@ weight: 40 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -MCP supports multiple transport mechanisms for client-server communication. The two standard transport mechanisms are STDIO and HTTP with Server-Sent Events (SSE). We recommend clients to support at least STDIO. +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) -## STDIO Transport -For STDIO transport, the client is responsible for launching the 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. +Clients **SHOULD** support stdio whenever possible. -The server MAY use standard error (STDERR) for logging purposes, but clients are not required to capture or process STDERR output. +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 - activate 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 + 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 + Client->>Server Process: Close stdin, terminate subprocess deactivate Server Process ``` -## HTTP with SSE Transport -For HTTP transport, the server operates as an independent process that can handle multiple client connections. The server provides two endpoints: +## 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 the server to push messages to clients -2. A regular HTTP endpoint for clients to send messages to the server +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. +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. @@ -45,7 +56,7 @@ sequenceDiagram participant Client participant Server - Client->>Server: SSE connection request + Client->>Server: Open SSE connection Server->>Client: endpoint event loop Message Exchange Client->>Server: HTTP POST messages @@ -56,6 +67,6 @@ sequenceDiagram ## Custom Transports -While STDIO and HTTP with SSE are the standardized transport protocols defined by MCP, 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. +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 maintain the core 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. +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. From 50fcf909784a2aa89d7d10b123397bf9c8dc3f97 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:37:26 +0000 Subject: [PATCH 10/33] Update versioning.md --- docs/specification/basic/versioning.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/specification/basic/versioning.md b/docs/specification/basic/versioning.md index d7fe316..ebccf42 100644 --- a/docs/specification/basic/versioning.md +++ b/docs/specification/basic/versioning.md @@ -3,16 +3,15 @@ title: Versioning type: docs weight: 80 --- -{{< callout type="info" >}} -**Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} -The Model Context Protocol uses string-based version identifiers following the format `YYYY-MM-DD` to indicate the last date significant changes were made. The current protocol version is `2024-11-05`. +The Model Context Protocol uses string-based version identifiers following the format `YYYY-MM-DD` to indicate the last date backwards incompatible changes were made. -Version negotiation happens during the initial handshake - clients declare their supported version in the `initialize` request, and servers respond with their preferred version. Clients and servers **MUST** agree on a compatible protocol version to proceed with communication. +The current protocol version is **{{< param protocolRevision >}}**. -A key aspect of the versioning scheme is that version strings may remain unchanged even when the protocol is updated, as long as changes maintain backwards compatibility. This allows for incremental improvements while preserving interoperability. +{{< callout type="info" >}} + The protocol version will _not_ be incremented when the protocol is updated, as long as the changes maintain backwards compatibility. This allows for incremental improvements while preserving interoperability. +{{< /callout >}} -Clients have the flexibility to support multiple protocol versions simultaneously. When connecting to a server, a client can indicate the latest version it supports while maintaining the ability to fall back to older versions if needed. However, servers will specify a single version they wish to use in their initialize response. +Version negotiation happens during [initialization]({{< ref "/specification/basic/lifecycle#initialization" >}}). Clients and servers **MAY** support multiple protocol versions simultaneously, but they **MUST** agree on a single version to use for the session. -The protocol provides appropriate error handling if version negotiation fails, allowing clients and servers to gracefully terminate connections when they cannot agree on a compatible version. +The protocol provides appropriate error handling if version negotiation fails, allowing clients to gracefully terminate connections when they cannot find a version compatible with the server. From d7bbe55915c169e6cf7f3dff2582949a81a88bfa Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:39:14 +0000 Subject: [PATCH 11/33] Add some missing protocol revision banners --- docs/specification/basic/_index.md | 4 ++++ docs/specification/basic/utilities/_index.md | 4 ++++ docs/specification/client/_index.md | 4 ++++ docs/specification/server/_index.md | 5 +++++ docs/specification/server/utilities/_index.md | 4 ++++ 5 files changed, 21 insertions(+) diff --git a/docs/specification/basic/_index.md b/docs/specification/basic/_index.md index 3fb93c5..8d47954 100644 --- a/docs/specification/basic/_index.md +++ b/docs/specification/basic/_index.md @@ -5,6 +5,10 @@ cascade: weight: 2 --- +{{< callout type="info" >}} +**Protocol Revision**: {{< param protocolRevision >}} +{{< /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 | diff --git a/docs/specification/basic/utilities/_index.md b/docs/specification/basic/utilities/_index.md index 03a6ffa..4557830 100644 --- a/docs/specification/basic/utilities/_index.md +++ b/docs/specification/basic/utilities/_index.md @@ -2,6 +2,10 @@ title: Utilities --- +{{< callout type="info" >}} +**Protocol Revision**: {{< param protocolRevision >}} +{{< /callout >}} + The Model Context Protocol includes several optional features that enhance the base protocol functionality. These features can be used independently to add capabilities like request cancellation, paginated results, and progress tracking. {{< cards >}} diff --git a/docs/specification/client/_index.md b/docs/specification/client/_index.md index 30c3bb7..db80981 100644 --- a/docs/specification/client/_index.md +++ b/docs/specification/client/_index.md @@ -4,3 +4,7 @@ cascade: type: docs weight: 4 --- + +{{< callout type="info" >}} +**Protocol Revision**: {{< param protocolRevision >}} +{{< /callout >}} diff --git a/docs/specification/server/_index.md b/docs/specification/server/_index.md index 80a4b18..21c760d 100644 --- a/docs/specification/server/_index.md +++ b/docs/specification/server/_index.md @@ -4,6 +4,11 @@ cascade: type: docs weight: 3 --- + +{{< callout type="info" >}} +**Protocol Revision**: {{< param protocolRevision >}} +{{< /callout >}} + Context primitives are the fundamental building blocks for providing context to language models via MCP. These primitives enable rich interactions between clients, servers, and language models. The key primitives are: - **Prompts**: Pre-defined templates or instructions that guide language model interactions diff --git a/docs/specification/server/utilities/_index.md b/docs/specification/server/utilities/_index.md index 85877a5..03cdb1a 100644 --- a/docs/specification/server/utilities/_index.md +++ b/docs/specification/server/utilities/_index.md @@ -1,3 +1,7 @@ --- title: Utilities --- + +{{< callout type="info" >}} +**Protocol Revision**: {{< param protocolRevision >}} +{{< /callout >}} From 75b37e045dc10f4dd6812b70d81ec53096953280 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:40:54 +0000 Subject: [PATCH 12/33] Link to revisions --- docs/specification/basic/versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/basic/versioning.md b/docs/specification/basic/versioning.md index ebccf42..35544c8 100644 --- a/docs/specification/basic/versioning.md +++ b/docs/specification/basic/versioning.md @@ -4,9 +4,9 @@ type: docs weight: 80 --- -The Model Context Protocol uses string-based version identifiers following the format `YYYY-MM-DD` to indicate the last date backwards incompatible changes were made. +The Model Context Protocol uses string-based version identifiers following the format `YYYY-MM-DD`, to indicate the last date backwards incompatible changes were made. -The current protocol version is **{{< param protocolRevision >}}**. +The current protocol version is **{{< param protocolRevision >}}**. [See all revisions]({{< ref "/specification/revisions" >}}). {{< callout type="info" >}} The protocol version will _not_ be incremented when the protocol is updated, as long as the changes maintain backwards compatibility. This allows for incremental improvements while preserving interoperability. From eb357093b299f17451a600682ac1d2c2ecd41589 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:46:22 +0000 Subject: [PATCH 13/33] Update utilities index --- docs/specification/basic/utilities/_index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/specification/basic/utilities/_index.md b/docs/specification/basic/utilities/_index.md index 4557830..6b6b8ff 100644 --- a/docs/specification/basic/utilities/_index.md +++ b/docs/specification/basic/utilities/_index.md @@ -6,10 +6,11 @@ title: Utilities **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol includes several optional features that enhance the base protocol functionality. These features can be used independently to add capabilities like request cancellation, paginated results, and progress tracking. +These optional features enhance the base protocol functionality with various utilities. {{< cards >}} - {{< card link="cancellation" title="Cancellation" icon="x-circle" >}} - {{< card link="pagination" title="Pagination" icon="document-duplicate" >}} - {{< card link="progress" title="Progress" icon="arrow-circle-right" >}} + {{< card link="ping" title="Ping" icon="status-online" >}} + {{< card link="cancellation" title="Cancellation" icon="x" >}} + {{< card link="pagination" title="Pagination" icon="collection" >}} + {{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}} From 943796274b58d71fa7a82c7d3afe68152df9fbf7 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:48:05 +0000 Subject: [PATCH 14/33] Update ping.md --- docs/specification/basic/utilities/ping.md | 30 ++++++++++++++-------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/specification/basic/utilities/ping.md b/docs/specification/basic/utilities/ping.md index 126b7f6..2ac305e 100644 --- a/docs/specification/basic/utilities/ping.md +++ b/docs/specification/basic/utilities/ping.md @@ -27,8 +27,17 @@ A ping request is a standard JSON-RPC request with no parameters: ## Behavior Requirements -1. The receiver MUST respond promptly to ping requests -2. If no response is received within a reasonable timeout period, the sender MAY: +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 @@ -41,19 +50,18 @@ sequenceDiagram participant Receiver Sender->>Receiver: ping request - Note over Receiver: Process immediately - Receiver->>Sender: response + Receiver->>Sender: empty response ``` ## Implementation Considerations -- Implementations SHOULD use 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 +- 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 -- Implementation SHOULD log ping failures for diagnostics +- Timeouts **SHOULD** be treated as connection failures +- Multiple failed pings **MAY** trigger connection reset +- Implementations **SHOULD** log ping failures for diagnostics From ce2a212811709c5ab974dc995899396e7a56fdfe Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 15:53:30 +0000 Subject: [PATCH 15/33] Update cancellation.md --- .../basic/utilities/cancellation.md | 47 +++++++++---------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/docs/specification/basic/utilities/cancellation.md b/docs/specification/basic/utilities/cancellation.md index 59a0375..0694a8c 100644 --- a/docs/specification/basic/utilities/cancellation.md +++ b/docs/specification/basic/utilities/cancellation.md @@ -29,52 +29,49 @@ When a party wants to cancel an in-progress request, it sends a `notifications/c ## Behavior Requirements -Both clients and servers MUST follow these requirements when handling cancellation: - -1. Cancellation notifications MUST only reference requests that: +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: +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: +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. Both parties MUST handle these race conditions gracefully: +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) - Note over Server: Processing may
complete before
cancellation arrives - opt If not completed - Note over Server: Stop processing - end + 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
completed before
cancellation arrives + else If not completed + Note over Server: Stop processing + end ``` ## Implementation Notes -- Servers SHOULD implement timeouts for long-running operations -- Clients SHOULD track pending requests that can be cancelled -- Both parties SHOULD log cancellation reasons for debugging -- UIs SHOULD provide feedback when cancellation is requested +- Both parties **SHOULD** log cancellation reasons for debugging +- Application UIs **SHOULD** indicate when cancellation is requested ## Error Handling -Invalid cancellation notifications SHOULD be ignored without error responses: +Invalid cancellation notifications **SHOULD** be ignored: - Unknown request IDs - Already completed requests From 032f61d265a5b2095d66b4be88b15596e6bd03b7 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:01:19 +0000 Subject: [PATCH 16/33] Update pagination.md --- .../basic/utilities/pagination.md | 59 +++++++++---------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/specification/basic/utilities/pagination.md b/docs/specification/basic/utilities/pagination.md index 2ba7369..62177e5 100644 --- a/docs/specification/basic/utilities/pagination.md +++ b/docs/specification/basic/utilities/pagination.md @@ -6,43 +6,44 @@ weight: 20 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) supports pagination for list operations that may return large result sets. Pagination allows clients to retrieve results in smaller chunks rather than all at once. +The Model Context Protocol (MCP) supports paginating list operations that may return large result sets. Pagination allows integrations to retrieve 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. The key components are: +Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages. -1. **Cursor**: An opaque string token representing a position in the result set -2. **Page Size**: Controlled by the server implementation -3. **Next Cursor**: Indicates if more results are available +* 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 -## Request Format +## Response Format -Paginated requests can include an optional cursor parameter: +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", - "method": "resources/list", - "params": { - "cursor": "eyJwYWdlIjogMn0=" + "id": "123", + "result": { + "resources": [...], + "nextCursor": "eyJwYWdlIjogM30=" } } ``` -## Response Format +## Request Format -Paginated responses include: -- The current page of results -- An optional `nextCursor` field if more results exist +After receiving a cursor, the client can _continue_ paginating by issuing a request including that cursor: ```json { "jsonrpc": "2.0", - "id": "123", - "result": { - "resources": [...], - "nextCursor": "eyJwYWdlIjogM30=" + "method": "resources/list", + "params": { + "cursor": "eyJwYWdlIjogMn0=" } } ``` @@ -55,13 +56,13 @@ sequenceDiagram participant Server Client->>Server: List Request (no cursor) - Server-->>Client: First Page + nextCursor - Client->>Server: List Request (with cursor) - Server-->>Client: Next Page + nextCursor - Note over Client,Server: Repeat until no nextCursor + loop Pagination Loop + Server-->>Client: Page of results + nextCursor + Client->>Server: List Request (with cursor) + end ``` -## Protocol Operations Supporting Pagination +## Operations Supporting Pagination The following MCP operations support pagination: @@ -72,21 +73,19 @@ The following MCP operations support pagination: ## Implementation Guidelines -1. Servers SHOULD: - - Use consistent page sizes +1. Servers **SHOULD**: - Provide stable cursors - Handle invalid cursors gracefully -2. Clients SHOULD: - - Store cursors for active pagination - - Handle missing nextCursor as end of results +2. Clients **SHOULD**: + - Treat a missing `nextCursor` as the end of results - Support both paginated and non-paginated flows -3. Both parties MUST treat cursors as opaque tokens: +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 cursor errors SHOULD be reported as standard JSON-RPC errors with code -32602 (Invalid params). +Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params). From 3457aa5dd54004c32a498df33eca4024ac986408 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:07:08 +0000 Subject: [PATCH 17/33] Update progress.md --- .../specification/basic/utilities/progress.md | 50 +++++++------------ 1 file changed, 19 insertions(+), 31 deletions(-) diff --git a/docs/specification/basic/utilities/progress.md b/docs/specification/basic/utilities/progress.md index 3e7cb38..1bb4d2e 100644 --- a/docs/specification/basic/utilities/progress.md +++ b/docs/specification/basic/utilities/progress.md @@ -10,11 +10,10 @@ The Model Context Protocol (MCP) supports optional progress tracking for long-ru ## Progress Flow -When a party wants to receive progress updates for a request, it includes a `progressToken` in the request metadata. Progress tokens can be any string or number value chosen by the sender, but MUST be unique across all active requests. The receiver can then send progress notifications containing: +When a party wants to _receive_ progress updates for a request, it includes a `progressToken` in the request metadata. -- The original progress token -- Current progress value -- Optional total value +* 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 { @@ -29,7 +28,11 @@ When a party wants to receive progress updates for a request, it includes a `pro } ``` -The receiver MAY then send progress notifications: +The receiver **MAY** then send progress notifications containing: + +- The original progress token +- The current progress value so far +- An optional "total" value ```json { @@ -43,24 +46,20 @@ The receiver MAY then send progress notifications: } ``` -## Behavior Requirements +* The `progress` value **MUST** increase with each notification, even if the total is unknown. +* The `progress` and the `total` values **MAY** be floating point. -Both clients and servers MUST follow these requirements when handling progress: +## Behavior Requirements -1. Progress notifications MUST only reference tokens that: +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: +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 -3. Senders SHOULD be prepared to: - - Handle missing progress notifications - - Receive notifications out of order - - Handle notifications after completion - ```mermaid sequenceDiagram participant Sender @@ -71,9 +70,9 @@ sequenceDiagram Note over Sender,Receiver: Progress updates loop Progress Updates - Receiver-->>Sender: Progress notification (50/100) - Receiver-->>Sender: Progress notification (75/100) - Receiver-->>Sender: Progress notification (100/100) + 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 @@ -82,17 +81,6 @@ sequenceDiagram ## Implementation Notes -- Receivers SHOULD use meaningful progress increments -- Senders SHOULD track active progress tokens -- Both parties SHOULD implement rate limiting -- Progress tracking SHOULD stop on completion - -## Error Handling - -Invalid progress notifications SHOULD be ignored without error responses: - -- Unknown progress tokens -- Out of order notifications -- Malformed notifications - -This maintains the "fire and forget" nature of notifications while allowing for race conditions in asynchronous communication. +- Senders and receivers **SHOULD** track active progress tokens +- Both parties **SHOULD** implement rate limiting to prevent flooding +- Progress notifications **MUST** stop after completion From 2dc33c5f96defdc85790d87ec7a345286b337935 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:08:49 +0000 Subject: [PATCH 18/33] Update server features index --- docs/specification/server/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/server/_index.md b/docs/specification/server/_index.md index 21c760d..096d28f 100644 --- a/docs/specification/server/_index.md +++ b/docs/specification/server/_index.md @@ -9,7 +9,7 @@ weight: 3 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -Context primitives are the fundamental building blocks for providing context to language models via MCP. These primitives enable rich interactions between clients, servers, and language models. The key primitives are: +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 From 56699383dcd1aa69ab019009b4732bcf7433edf3 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:16:21 +0000 Subject: [PATCH 19/33] Move pagination to server utilities --- docs/specification/basic/utilities/_index.md | 1 - docs/specification/server/utilities/logging.md | 7 ------- .../{basic => server}/utilities/pagination.md | 3 +-- 3 files changed, 1 insertion(+), 10 deletions(-) rename docs/specification/{basic => server}/utilities/pagination.md (94%) diff --git a/docs/specification/basic/utilities/_index.md b/docs/specification/basic/utilities/_index.md index 6b6b8ff..5abbf2b 100644 --- a/docs/specification/basic/utilities/_index.md +++ b/docs/specification/basic/utilities/_index.md @@ -11,6 +11,5 @@ These optional features enhance the base protocol functionality with various uti {{< cards >}} {{< card link="ping" title="Ping" icon="status-online" >}} {{< card link="cancellation" title="Cancellation" icon="x" >}} - {{< card link="pagination" title="Pagination" icon="collection" >}} {{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}} diff --git a/docs/specification/server/utilities/logging.md b/docs/specification/server/utilities/logging.md index 4e24563..25dad0b 100644 --- a/docs/specification/server/utilities/logging.md +++ b/docs/specification/server/utilities/logging.md @@ -166,10 +166,3 @@ Servers SHOULD return standard JSON-RPC errors for common failure cases: - Validate all data fields - Control log access - Monitor for sensitive content - -## See Also - -{{< cards >}} -{{< card link="/utilities/pagination" title="Pagination" icon="document-duplicate" >}} -{{< card link="/server/utilities/progress" title="Progress Tracking" icon="arrow-circle-right" >}} -{{< /cards >}} diff --git a/docs/specification/basic/utilities/pagination.md b/docs/specification/server/utilities/pagination.md similarity index 94% rename from docs/specification/basic/utilities/pagination.md rename to docs/specification/server/utilities/pagination.md index 62177e5..c5d951f 100644 --- a/docs/specification/basic/utilities/pagination.md +++ b/docs/specification/server/utilities/pagination.md @@ -1,12 +1,11 @@ --- title: Pagination -weight: 20 --- {{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) supports paginating list operations that may return large result sets. Pagination allows integrations to retrieve results in smaller chunks rather than all at once. +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. From c5dba5e5476eb1303f22152c285935d02566e1fc Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:20:21 +0000 Subject: [PATCH 20/33] Update prompts.md --- docs/specification/server/prompts.md | 55 ++++++++++++---------------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/specification/server/prompts.md b/docs/specification/server/prompts.md index 39d82e0..5441408 100644 --- a/docs/specification/server/prompts.md +++ b/docs/specification/server/prompts.md @@ -11,15 +11,19 @@ The Model Context Protocol (MCP) provides a standardized way for servers to expo ## User Interaction Model -Prompts in MCP are commonly implemented through user-initiated interactions. One recommended implementation pattern is exposing prompts through user-initiated commands in the user interface, which allows users to naturally discover and invoke available prompts. An example of this pattern are slash commands. +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: ![Example of prompt exposed as slash command](slash-command.png) -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. +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 include a `prompts` capability in their `ServerCapabilities` during initialization: +Servers that support prompts **MUST** declare the `prompts` capability during [initialization]({{< ref "/specification/basic/lifecycle#initialization" >}}): ```json { "capabilities": { @@ -30,23 +34,13 @@ Servers that support prompts MUST include a `prompts` capability in their `Serve } ``` -To omit change notifications, the server would not include `listChanged`: - -```json -{ - "capabilities": { - "prompts": {} - } -} -``` - -The `listChanged` property indicates that the server supports notifications about changes to the prompt list. +`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 through the standard cursor mechanism. +To retrieve available prompts, clients send a `prompts/list` request. This operation supports [pagination]({{< ref "/specification/server/utilities/pagination" >}}). **Request:** ```json @@ -69,7 +63,7 @@ To retrieve available prompts, clients send a `prompts/list` request. This opera "prompts": [ { "name": "code_review", - "description": "Analyze code quality and suggest improvements", + "description": "Asks the LLM to analyze code quality and suggest improvements", "arguments": [ { "name": "code", @@ -86,7 +80,7 @@ To retrieve available prompts, clients send a `prompts/list` request. This opera ### Getting a Prompt -To retrieve a specific prompt, clients send a `prompts/get` request. Arguments support auto-completion through [the completion API]({{< relref "utilities/completion.md" >}}): +To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be auto-completed through [the completion API]({{< ref "/specification/server/utilities/completion" >}})): **Request:** ```json @@ -115,7 +109,7 @@ To retrieve a specific prompt, clients send a `prompts/get` request. Arguments s "role": "user", "content": { "type": "text", - "text": "Please review this code..." + "text": "Please review this Python code:\ndef hello():\n print('world')" } } ] @@ -125,7 +119,7 @@ To retrieve a specific prompt, clients send a `prompts/get` request. Arguments s ### List Changed Notification -When prompts change, servers that support `listChanged` MAY send a notification: +When the list of available prompts changes, servers that declared the `listChanged` capability **SHOULD** send a notification: ```json { @@ -149,10 +143,12 @@ sequenceDiagram Client->>Server: prompts/get Server-->>Client: Prompt content - Note over Client,Server: Changes - Server--)Client: prompts/list_changed - Client->>Server: prompts/list - Server-->>Client: Updated prompts + opt listChanged + Note over Client,Server: Changes + Server--)Client: prompts/list_changed + Client->>Server: prompts/list + Server-->>Client: Updated prompts + end ``` ## Data Types @@ -223,15 +219,10 @@ Servers SHOULD return standard JSON-RPC errors for common failure cases: ## 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 +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 arguments to prevent injection attacks or unauthorized access to resources. - -## See Also -{{< cards >}} -{{< card link="/server/utilities/completion" title="Completion API" icon="code" >}} -{{< /cards >}} +Implementations **MUST** carefully validate all prompt inputs and outputs to prevent injection attacks or unauthorized access to resources. From eb51db08766e24ceba55f6354248eab774d3f9b4 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:29:04 +0000 Subject: [PATCH 21/33] Update resources.md --- docs/specification/server/resources.md | 73 ++++++++++++++------------ 1 file changed, 40 insertions(+), 33 deletions(-) diff --git a/docs/specification/server/resources.md b/docs/specification/server/resources.md index adfdc19..94a000f 100644 --- a/docs/specification/server/resources.md +++ b/docs/specification/server/resources.md @@ -12,15 +12,20 @@ The Model Context Protocol (MCP) provides a standardized way for servers to expo ## User Interaction Model -Resources in MCP are designed to be application-driven, with clients determining how to incorporate context based on their needs. Applications can expose resources through UI elements for explicit selection, while implementing intelligent features for automatic context inclusion, searching and filtering. A recommended pattern is a context picker showing resources in a tree/list view that combines manual selection with automated context handling. +Resources in MCP are designed to be **application-driven**, with clients determining how to incorporate context based on their needs. + +For example, applications could: +* Expose resources through UI elements for explicit selection, in a tree or list view +* Allow the user to search through and filter available resources +* Implement automatic context inclusion, based on heuristics or the AI model's selection ![Example of resource context picker](resource-picker.png) -However, implementations are free to expose resources through any interface pattern that suits their needs - the protocol itself does not mandate any specific user interaction model. +However, implementations are free to expose resources through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model. ## Capabilities -Servers that support resources MUST include a `resources` capability in their `ServerCapabilities` during initialization. The capability object can specify optional features: +Servers that support resources **MUST** declare the `resources` capability: ```json { @@ -33,7 +38,11 @@ Servers that support resources MUST include a `resources` capability in their `S } ``` -Both `subscribe` and `listChanged` are optional - servers can support neither, either, or both: +The capability supports two optional features: +- `subscribe`: whether the client can subscribe to be notified of changes to individual resources. +- `listChanged`: whether the server will emit notifications when the list of available resources changes. + +Both `subscribe` and `listChanged` are optional—servers can support neither, either, or both: ```json { @@ -63,15 +72,11 @@ Both `subscribe` and `listChanged` are optional - servers can support neither, e } ``` -The capability supports two optional features: -- `subscribe`: Server supports subscribing to resource updates -- `listChanged`: Server supports notifications about changes to the resource list - ## Protocol Messages ### Listing Resources -To discover available resources, clients send a `resources/list` request. This operation supports pagination through the standard cursor mechanism. +To discover available resources, clients send a `resources/list` request. This operation supports [pagination]({{< ref "/specification/server/utilities/pagination" >}}). **Request:** ```json @@ -94,7 +99,7 @@ To discover available resources, clients send a `resources/list` request. This o "resources": [ { "uri": "file:///project/src/main.rs", - "name": "Main source file", + "name": "main.rs", "description": "Primary application entry point", "mimeType": "text/x-rust" } @@ -139,7 +144,7 @@ To retrieve resource contents, clients send a `resources/read` request: ### Resource Templates -Resource templates allow servers to expose parameterized resources using URI templates ([RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570)): +Resource templates allow servers to expose parameterized resources using [URI templates](https://datatracker.ietf.org/doc/html/rfc6570): **Request:** ```json @@ -255,22 +260,31 @@ Resources can contain either text or binary data: ## Common URI Schemes -The protocol defines several standard URI schemes: +The protocol defines several standard URI schemes. This list not exhaustive—implementations are always free to use additional, custom URI schemes. + +### https:// + +Used to represent a resource available on the web. + +Servers **SHOULD** use this scheme only when the client is able to fetch and load the resource directly from the web on its own—that is, it doesn’t need to read the resource via the MCP server. -| Scheme | Description | Notes | -|-----------|---------------------------------------|------------------------------------------| -| file:// | Filesystem-like resources | Primary scheme for code and text files | -| https:// | Web resources | For directly fetchable web content | -| s3:// | S3-compatible storage | For cloud storage access | -| git:// | Git repositories | For version control integration | -| data: | Inline data | For small embedded resources | +For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a custom one, even if the server will itself be downloading resource contents over the internet. + +### file:// + +Used to identify resources that behave like a filesystem. However, the resources do not need to map to an actual physical filesystem. + +MCP servers **MAY** identify file:// resources with an [XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14), like `inode/directory`, to represent non-regular files (such as directories) that don’t otherwise have a standard MIME type. + +### git:// + +Git version control integration. ## Error Handling Servers SHOULD return standard JSON-RPC errors for common failure cases: -- Resource not found: `-32001` -- Permission denied: `-32002` +- Resource not found: `-32002` - Internal errors: `-32603` Example error: @@ -279,7 +293,7 @@ Example error: "jsonrpc": "2.0", "id": 5, "error": { - "code": -32001, + "code": -32002, "message": "Resource not found", "data": { "uri": "file:///nonexistent.txt" @@ -290,14 +304,7 @@ Example error: ## Security Considerations -1. Servers MUST validate all resource URIs -2. Access controls SHOULD be implemented for sensitive resources -3. Binary data MUST be properly encoded -4. Resource permissions SHOULD be checked before operations - -## See Also - -{{< cards >}} -{{< card link="/server/utilities/pagination" title="Pagination" icon="document-duplicate" >}} -{{< card link="/server/utilities/progress" title="Progress Tracking" icon="arrow-circle-right" >}} -{{< /cards >}} +1. Servers **MUST** validate all resource URIs +2. Access controls **SHOULD** be implemented for sensitive resources +3. Binary data **MUST** be properly encoded +4. Resource permissions **SHOULD** be checked before operations From 85fe3a95996f776caeca42deb0e42d19795d702b Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:30:27 +0000 Subject: [PATCH 22/33] Resources support completion --- docs/specification/server/prompts.md | 2 +- docs/specification/server/resources.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/server/prompts.md b/docs/specification/server/prompts.md index 5441408..eda569f 100644 --- a/docs/specification/server/prompts.md +++ b/docs/specification/server/prompts.md @@ -80,7 +80,7 @@ To retrieve available prompts, clients send a `prompts/list` request. This opera ### 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/server/utilities/completion" >}})): +To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be auto-completed through [the completion API]({{< ref "/specification/server/utilities/completion" >}}). **Request:** ```json diff --git a/docs/specification/server/resources.md b/docs/specification/server/resources.md index 94a000f..6f102e4 100644 --- a/docs/specification/server/resources.md +++ b/docs/specification/server/resources.md @@ -144,7 +144,7 @@ To retrieve resource contents, clients send a `resources/read` request: ### Resource Templates -Resource templates allow servers to expose parameterized resources using [URI templates](https://datatracker.ietf.org/doc/html/rfc6570): +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]({{< ref "/specification/server/utilities/completion" >}}). **Request:** ```json From b5c238f07eed7e69aa42ca25e3e27f9a759e9930 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:50:22 +0000 Subject: [PATCH 23/33] Update tools --- docs/specification/server/resources.md | 11 ++++++ docs/specification/server/tools.md | 52 ++++++++++++-------------- 2 files changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/specification/server/resources.md b/docs/specification/server/resources.md index 6f102e4..06b88eb 100644 --- a/docs/specification/server/resources.md +++ b/docs/specification/server/resources.md @@ -173,6 +173,17 @@ Resource templates allow servers to expose parameterized resources using [URI te } ``` +### List Changed Notification + +When the list of available resources changes, servers that declared the `listChanged` capability **SHOULD** send a notification: + +```json +{ + "jsonrpc": "2.0", + "method": "notifications/resources/list_changed" +} +``` + ### Subscriptions The protocol supports optional subscriptions to resource changes. Clients can subscribe to specific resources and receive notifications when they change: diff --git a/docs/specification/server/tools.md b/docs/specification/server/tools.md index e79bb81..b512cd9 100644 --- a/docs/specification/server/tools.md +++ b/docs/specification/server/tools.md @@ -8,27 +8,26 @@ weight: 40 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by language models through clients. Tools enable models to perform actions or retrieve information beyond their training data, such as querying databases, calling external APIs, or executing commands. Each tool is uniquely identified by a name and includes metadata describing its capabilities and requirements. +The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by language models. Tools enable models to interact with external systems, such as querying databases, calling APIs, or performing computations. Each tool is uniquely identified by a name and includes metadata describing its schema. ## User Interaction Model -Tools in MCP are commonly surfaced through AI assistant or chatbot interfaces, where the language model can discover and invoke tools based on the conversation context. A recommended pattern is displaying available tools in the chat interface with visual indicators when they are invoked, along with confirmation prompts for sensitive operations. +Tools in MCP are designed to be **model-controlled**, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts. -However, implementations are free to expose tools through any interface pattern that suits their needs - the protocol itself does not mandate any specific user interaction model. +However, implementations are free to expose tools through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model. -## Capabilities - -Servers that support tools MUST include a `tools` capability in their `ServerCapabilities` during initialization. The basic tools capability can be specified with an empty object: +{{< callout type="warning" >}} + For trust & safety and security, there **SHOULD** always be a human in the loop with the ability to deny tool invocations. + + Applications **SHOULD**: + * Provide UI that makes clear which tools are being exposed to the AI model + * Insert clear visual indicators when tools are invoked + * Present confirmation prompts to the user for operations, to ensure a human is in the loop +{{< /callout >}} -```json -{ - "capabilities": { - "tools": {} - } -} -``` +## Capabilities -For servers that support notifications about tool list changes, the optional `listChanged` property should be set to true: +Servers that support tools **MUST** declare the `tools` capability: ```json { @@ -40,13 +39,13 @@ For servers that support notifications about tool list changes, the optional `li } ``` -The `listChanged` property indicates that the server supports notifications about changes to the tool list. When omitted or set to false, clients should not expect to receive tool list change notifications. +`listChanged` indicates whether the server will emit notifications when the list of available tools changes. ## Protocol Messages ### Listing Tools -To discover available tools, clients send a `tools/list` request. This operation supports pagination through the standard cursor mechanism. +To discover available tools, clients send a `tools/list` request. This operation supports [pagination]({{< ref "/specification/server/utilities/pagination" >}}). **Request:** ```json @@ -123,7 +122,7 @@ To invoke a tool, clients send a `tools/call` request: ### List Changed Notification -When tools change, servers that support `listChanged` MAY send a notification: +When the list of available tools changes, servers that declared the `listChanged` capability **SHOULD** send a notification: ```json { @@ -190,6 +189,9 @@ Tool results can contain multiple content items of different types: ``` #### Embedded Resources + +[Resources]({{< ref "/specification/server/resources" >}}) **MAY** be embedded, to provide additional context or data, behind a URI that can be subscribed to or fetched again by the client later: + ```json { "type": "resource", @@ -205,12 +207,12 @@ Tool results can contain multiple content items of different types: Tools use two error reporting mechanisms: -1. Protocol Errors: Standard JSON-RPC errors for issues like: +1. **Protocol Errors**: Standard JSON-RPC errors for issues like: - Unknown tools - Invalid arguments - Server errors -2. Tool Execution Errors: Reported in successful responses with `isError: true`: +2. **Tool Execution Errors**: Reported in tool results with `isError: true`: - API failures - Invalid input data - Business logic errors @@ -244,21 +246,15 @@ Example tool execution error: ## Security Considerations -1. Servers MUST: +1. Servers **MUST**: - Validate all tool inputs - Implement proper access controls - Rate limit tool invocations - Sanitize tool outputs -2. Clients SHOULD: +2. Clients **SHOULD**: - Prompt for user confirmation on sensitive operations + - Show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration - Validate tool results before passing to LLM - Implement timeouts for tool calls - Log tool usage for audit purposes - -## See Also - -{{< cards >}} -{{< card link="/server/utilities/pagination" title="Pagination" icon="document-duplicate" >}} -{{< card link="/server/utilities/progress" title="Progress Tracking" icon="arrow-circle-right" >}} -{{< /cards >}} From 647a2891e1d46d49bfff3f3e73325d42cd8a4c47 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:51:18 +0000 Subject: [PATCH 24/33] Update "contributions" --- docs/specification/contributing/_index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/specification/contributing/_index.md b/docs/specification/contributing/_index.md index 438a8a5..8b1bbae 100644 --- a/docs/specification/contributing/_index.md +++ b/docs/specification/contributing/_index.md @@ -6,10 +6,8 @@ cascade: breadcrumbs: false --- -The Model Context Protocol specification welcomes contributions from the community. - -Please review our [contributing guidelines](https://github.com/modelcontextprotocol/specification/blob/main/CONTRIBUTING.md) for details on how to submit changes. +We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/specification/blob/main/CONTRIBUTING.md) for details on how to submit changes. All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/specification/blob/main/CODE_OF_CONDUCT.md). -For questions and discussions, please use the [GitHub Discussion forums](https://github.com/modelcontextprotocol/specification/discussions). +For questions and discussions, please use [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions). From 69b5e5b2b9dd749342ab9bfba88c72258220d10f Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:56:33 +0000 Subject: [PATCH 25/33] Update revisions, introduce additional "current" status --- docs/specification/revisions/2024-11-05.md | 4 ++-- docs/specification/revisions/_index.md | 9 +++++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/specification/revisions/2024-11-05.md b/docs/specification/revisions/2024-11-05.md index 8ae004a..465a00d 100644 --- a/docs/specification/revisions/2024-11-05.md +++ b/docs/specification/revisions/2024-11-05.md @@ -1,5 +1,5 @@ --- -title: 2024-11-05 (Final) +title: 2024-11-05 (Current) weight: 1 --- -This is the initial version of the specification. This revision has been finalized. +This is the current version of the specification. This revision may continue to receive backwards compatible changes. diff --git a/docs/specification/revisions/_index.md b/docs/specification/revisions/_index.md index 5c3f358..dbe14f7 100644 --- a/docs/specification/revisions/_index.md +++ b/docs/specification/revisions/_index.md @@ -3,6 +3,11 @@ title: Revisions cascade: type: docs --- -The Model Context Protocol uses revisions that define specific protocol behaviors for each version. Each protocol revision provides guarantees about the functionality and semantics available. The protocol version is exchanged during initialization (see [Versioning]({{< relref "../basic/versioning.md" >}})). -Revisions can be marked as either DRAFT (in-progress specifications) or FINAL (completed specifications). DRAFT revisions may change at any time, while FINAL revisions remain stable once published. +This page lists the different revisions of the Model Context Protocol. See [Versioning]({{< ref "/specification/basic/versioning" >}}) for more information about how the protocol is versioned. + +Revisions may be marked as: + +* **Draft**: in-progress specifications, not yet ready for consumption. +* **Current**: the current protocol version, which is ready for use and may continue to receive [backwards compatible changes]({{< ref "/specification/basic/versioning" >}}). +* **Final**: past, complete specifications that will not be changed. From 5ba9ba253e166cc45c86875dd7e30abd1daa55a4 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 16:59:39 +0000 Subject: [PATCH 26/33] Update server utilities index --- docs/specification/server/utilities/_index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/specification/server/utilities/_index.md b/docs/specification/server/utilities/_index.md index 03cdb1a..4a0d96a 100644 --- a/docs/specification/server/utilities/_index.md +++ b/docs/specification/server/utilities/_index.md @@ -5,3 +5,11 @@ title: Utilities {{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} {{< /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 >}} From 4fd8cef1918b9066078a0b7330b085e38347c498 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:02:06 +0000 Subject: [PATCH 27/33] Update completion.md --- .../server/utilities/completion.md | 23 ++++++++----------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/specification/server/utilities/completion.md b/docs/specification/server/utilities/completion.md index 1b5a1c4..7c43c4c 100644 --- a/docs/specification/server/utilities/completion.md +++ b/docs/specification/server/utilities/completion.md @@ -6,13 +6,15 @@ title: Completion **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) provides a standardized way for servers to provide argument completion suggestions for prompts and resource URIs. This enables rich, IDE-like experiences where users receive contextual suggestions while entering argument values. +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. A recommended implementation pattern is showing completion suggestions in a dropdown or popup menu as users type, with the ability to filter and select from available options. +Completion in MCP is designed to support interactive user experiences similar to IDE code completion. -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. +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 @@ -61,7 +63,7 @@ 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}"}` | +| `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` | ### Completion Results @@ -103,28 +105,21 @@ sequenceDiagram ## Implementation Considerations -1. Servers SHOULD: +1. Servers **SHOULD**: - Return suggestions sorted by relevance - Implement fuzzy matching where appropriate - Rate limit completion requests - Validate all inputs -2. Clients SHOULD: +2. Clients **SHOULD**: - Debounce rapid completion requests - Cache completion results where appropriate - Handle missing or partial results gracefully ## Security -Implementations MUST: +Implementations **MUST**: - Validate all completion inputs - Implement appropriate rate limiting - Control access to sensitive suggestions - Prevent completion-based information disclosure - -## See Also - -{{< cards >}} -{{< card link="/server/prompts" title="Prompts" icon="chat" >}} -{{< card link="/server/resources" title="Resources" icon="document" >}} -{{< /cards >}} From c11466354a4da06ca41e7f34ff17624b535744af Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:05:03 +0000 Subject: [PATCH 28/33] Update logging.md --- .../specification/server/utilities/logging.md | 54 ++++--------------- 1 file changed, 11 insertions(+), 43 deletions(-) diff --git a/docs/specification/server/utilities/logging.md b/docs/specification/server/utilities/logging.md index 25dad0b..3104b4f 100644 --- a/docs/specification/server/utilities/logging.md +++ b/docs/specification/server/utilities/logging.md @@ -10,11 +10,11 @@ The Model Context Protocol (MCP) provides a standardized way for servers to send ## 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. +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 support logging MUST include a `logging` capability in their `ServerCapabilities` during initialization: +Servers that emit log message notifications **MUST** declare the `logging` capability: ```json { @@ -26,7 +26,7 @@ Servers that support logging MUST include a `logging` capability in their `Serve ## Log Levels -The protocol defines standard syslog severity levels as specified in [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1): +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 | |------------|--------------------------------------|----------------------------------------| @@ -43,7 +43,7 @@ The protocol defines standard syslog severity levels as specified in [RFC 5424]( ### Setting Log Level -To configure the minimum log level, clients send a `logging/setLevel` request: +To configure the minimum log level, clients **MAY** send a `logging/setLevel` request: **Request:** ```json @@ -101,67 +101,35 @@ sequenceDiagram Note over Server: Only sends error level
and above ``` -## Common Message Patterns - -### Operation Progress -```json -{ - "level": "info", - "logger": "file_processor", - "data": { - "operation": "scan", - "progress": "50%", - "filesProcessed": 150, - "totalFiles": 300 - } -} -``` - -### Error Reporting -```json -{ - "level": "error", - "logger": "git_clone", - "data": { - "error": "Repository unreachable", - "details": { - "repository": "github.com/example/repo", - "attempt": 2, - "maxAttempts": 3 - } - } -} -``` - ## Error Handling -Servers SHOULD return standard JSON-RPC errors for common failure cases: +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: +1. Servers **SHOULD**: - Rate limit log messages - Include relevant context in data field - Use consistent logger names - Remove sensitive information -2. Clients SHOULD: - - Handle out-of-order messages +2. Clients **MAY**: + - Present log messages in the UI - Implement log filtering/search - Display severity visually - - Support log persistence + - Persist log messages ## Security -1. Log messages MUST NOT contain: +1. Log messages **MUST NOT** contain: - Credentials or secrets - Personal identifying information - Internal system details that could aid attacks -2. Implementations SHOULD: +2. Implementations **SHOULD**: - Rate limit messages - Validate all data fields - Control log access From d9aae475464b427412907f40e6ab3508539af1da Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:10:53 +0000 Subject: [PATCH 29/33] Update client features index --- docs/specification/client/_index.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/specification/client/_index.md b/docs/specification/client/_index.md index db80981..d09ef5a 100644 --- a/docs/specification/client/_index.md +++ b/docs/specification/client/_index.md @@ -8,3 +8,10 @@ weight: 4 {{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} {{< /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 >}} From 924cce9c1cdb1fba62713d90ddf749268fe892fc Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:15:44 +0000 Subject: [PATCH 30/33] Update roots.md --- docs/specification/client/roots.md | 36 +++++++++++++----------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/docs/specification/client/roots.md b/docs/specification/client/roots.md index 6748e84..d80deab 100644 --- a/docs/specification/client/roots.md +++ b/docs/specification/client/roots.md @@ -8,19 +8,21 @@ weight: 40 **Protocol Revision**: {{< param protocolRevision >}} {{< /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. +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. A recommended implementation pattern is 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. +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: ![Example of root selection interface](root-picker.png) -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. +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 include a `roots` capability in their `ClientCapabilities` during initialization: +Clients that support prompts **MUST** declare the `roots` capability during [initialization]({{< ref "/specification/basic/lifecycle#initialization" >}}): ```json { @@ -32,13 +34,13 @@ Clients that support roots MUST include a `roots` capability in their `ClientCap } ``` -The `listChanged` property indicates whether the client supports notifications about changes to the root list. +`listChanged` indicates whether the client will emit notifications when the list of roots changes. ## Protocol Messages ### Listing Roots -To retrieve available roots, servers send a `roots/list` request: +To retrieve roots, servers send a `roots/list` request: **Request:** ```json @@ -99,8 +101,8 @@ sequenceDiagram A root definition includes: -- `uri`: Unique identifier for the root (currently restricted to `file://` URIs) -- `name`: Optional human-readable name for display purposes +- `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: @@ -131,7 +133,6 @@ Example roots for different use cases: Clients SHOULD return standard JSON-RPC errors for common failure cases: - Client does not support roots: `-32601` (Method not found) -- Access denied: `-32002` - Internal errors: `-32603` Example error: @@ -151,34 +152,27 @@ Example error: ## Security Considerations -1. Clients MUST: +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: +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: +1. Clients **SHOULD**: + - Prompt users for consent before exposing roots to servers - Provide clear user interfaces for root management - - Support automatic root detection where applicable - Validate root accessibility before exposing - Monitor for root changes -2. Servers SHOULD: +2. Servers **SHOULD**: - Check for roots capability before usage - Handle root list changes gracefully - Respect root boundaries in operations - Cache root information appropriately - -## See Also - -{{< cards >}} -{{< card link="/basic/lifecycle" title="Lifecycle" icon="refresh" >}} -{{< card link="/server/resources" title="Resources" icon="document" >}} -{{< /cards >}} From 519eb3238d9c43ff8cc333766f82acc7edf7c70e Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:24:44 +0000 Subject: [PATCH 31/33] Update sampling.md --- docs/specification/client/sampling.md | 70 +++++++++++---------------- 1 file changed, 28 insertions(+), 42 deletions(-) diff --git a/docs/specification/client/sampling.md b/docs/specification/client/sampling.md index a8c46a9..95e4563 100644 --- a/docs/specification/client/sampling.md +++ b/docs/specification/client/sampling.md @@ -8,22 +8,26 @@ weight: 40 **Protocol Revision**: {{< param protocolRevision >}} {{< /callout >}} -The Model Context Protocol (MCP) provides a standardized way for servers to request generations from language models via clients. This unique reverse flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities. Servers can request text or image-based interactions and optionally include context from MCP servers in their prompts. +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 is designed around a human-in-the-loop approval pattern. A recommended implementation exposes sampling requests through an approval UI that allows users to: +Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to occur _nested_ inside other MCP server features. -1. Review incoming sampling requests -2. Inspect model selections and parameters -3. View and edit prompts before sending -4. Review generated responses before delivery +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. -However, 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 include a `sampling` capability in their `ClientCapabilities` during initialization: +Clients that support sampling **MUST** declare the `sampling` capability during [initialization]({{< ref "/specification/basic/lifecycle#initialization" >}}): ```json { @@ -33,8 +37,6 @@ Clients that support sampling MUST include a `sampling` capability in their `Cli } ``` -The empty object indicates basic sampling support with no additional features. - ## Protocol Messages ### Creating Messages @@ -67,8 +69,7 @@ To request a language model generation, servers send a `sampling/createMessage` "speedPriority": 0.5 }, "systemPrompt": "You are a helpful assistant.", - "maxTokens": 100, - "temperature": 0.7 + "maxTokens": 100 } } ``` @@ -151,9 +152,9 @@ To solve this, MCP implements a preference system that combines abstract capabil 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 +- `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 @@ -161,8 +162,8 @@ While priorities help select models based on characteristics, `hints` allow serv - 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 +- Clients **MAY** map hints to equivalent models from different providers +- Hints are advisory—clients make final model selection For example: ```json @@ -171,8 +172,8 @@ For example: {"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 + "costPriority": 0.3, // Cost is less important + "speedPriority": 0.8, // Speed is very important "intelligencePriority": 0.5 // Moderate capability needs } ``` @@ -181,12 +182,7 @@ The client processes these preferences to select an appropriate model from its a ## Error Handling -Clients SHOULD return standard JSON-RPC errors for common failure cases: - -- User rejection: `-32001` -- Model unavailable: `-32002` -- Invalid parameters: `-32602` -- Context length exceeded: `-32003` +Clients **SHOULD** return errors for common failure cases: Example error: ```json @@ -194,26 +190,16 @@ Example error: "jsonrpc": "2.0", "id": 1, "error": { - "code": -32001, - "message": "User rejected sampling request", - "data": { - "reason": "Content policy violation" - } + "code": -1, + "message": "User rejected sampling request" } } ``` ## Security Considerations -1. Clients MUST implement user approval controls -2. Both parties SHOULD validate message content -3. Servers SHOULD respect model preference hints -4. Clients SHOULD implement rate limiting -5. Both parties MUST handle sensitive data appropriately - -## See Also - -{{< cards >}} -{{< card link="/utilities/progress" title="Progress Tracking" icon="arrow-circle-right" >}} -{{< card link="/utilities/cancellation" title="Request Cancellation" icon="x-circle" >}} -{{< /cards >}} +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 From 432665321a3a27bf5a29085b6b39d072e2f409e1 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:25:29 +0000 Subject: [PATCH 32/33] Remove broken image from "roots" --- docs/specification/client/roots.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/specification/client/roots.md b/docs/specification/client/roots.md index d80deab..5113cfd 100644 --- a/docs/specification/client/roots.md +++ b/docs/specification/client/roots.md @@ -14,9 +14,7 @@ The Model Context Protocol (MCP) provides a standardized way for clients to expo 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: - -![Example of root selection interface](root-picker.png) +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. From 5eb7663ad6b133cd937cb423f63ba8b61c36c8cb Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 22 Nov 2024 17:33:25 +0000 Subject: [PATCH 33/33] Add security and T&S section to spec page --- docs/specification/_index.md | 39 ++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/specification/_index.md b/docs/specification/_index.md index be58725..a314274 100644 --- a/docs/specification/_index.md +++ b/docs/specification/_index.md @@ -59,6 +59,45 @@ Clients may offer the following feature to servers: - Error reporting - Logging +## Security and Trust & Safety + +The Model Context Protocol enables powerful capabilities through arbitrary data access and code execution paths. With this power comes important security and trust considerations that all implementors must carefully address. + +### Key Principles + +1. **User Consent and Control** + - Users must explicitly consent to and understand all data access and operations + - Users must retain control over what data is shared and what actions are taken + - Implementors should provide clear UIs for reviewing and authorizing activities + +2. **Data Privacy** + - Hosts must obtain explicit user consent before exposing user data to servers + - Hosts must not transmit resource data elsewhere without user consent + - User data should be protected with appropriate access controls + +3. **Tool Safety** + - Tools represent arbitrary code execution and must be treated with appropriate caution + - Hosts must obtain explicit user consent before invoking any tool + - Users should understand what each tool does before authorizing its use + +4. **LLM Sampling Controls** + - Users must explicitly approve any LLM sampling requests + - Users should control: + - Whether sampling occurs at all + - The actual prompt that will be sent + - What results the server can see + - The protocol intentionally limits server visibility into prompts + +### Implementation Guidelines + +While MCP itself cannot enforce these security principles at the protocol level, implementors **SHOULD**: + +1. Build robust consent and authorization flows into their applications +2. Provide clear documentation of security implications +3. Implement appropriate access controls and data protections +4. Follow security best practices in their integrations +5. Consider privacy implications in their feature designs + ## Learn More Explore the detailed specification for each protocol component: