diff --git a/docs/specification/2024-11-05/_index.md b/docs/specification/2024-11-05/_index.md index 0ca189683..5ec6a9275 100644 --- a/docs/specification/2024-11-05/_index.md +++ b/docs/specification/2024-11-05/_index.md @@ -1,15 +1,13 @@ --- -title: Specification (Latest) +linkTitle: 2024-11-05 (Final) +title: Model Context Protocol specification cascade: type: docs breadcrumbs: false -weight: 10 -aliases: - - /latest +weight: 2 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and diff --git a/docs/specification/2024-11-05/basic/_index.md b/docs/specification/2024-11-05/basic/_index.md index f1934e821..b86fb10cf 100644 --- a/docs/specification/2024-11-05/basic/_index.md +++ b/docs/specification/2024-11-05/basic/_index.md @@ -5,8 +5,7 @@ cascade: weight: 2 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} All messages between MCP clients and servers **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines diff --git a/docs/specification/2024-11-05/basic/lifecycle.md b/docs/specification/2024-11-05/basic/lifecycle.md index 41342bb74..6ee570dcd 100644 --- a/docs/specification/2024-11-05/basic/lifecycle.md +++ b/docs/specification/2024-11-05/basic/lifecycle.md @@ -4,8 +4,7 @@ type: docs weight: 30 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management. diff --git a/docs/specification/2024-11-05/basic/messages.md b/docs/specification/2024-11-05/basic/messages.md index a979ce50d..8a1c4d113 100644 --- a/docs/specification/2024-11-05/basic/messages.md +++ b/docs/specification/2024-11-05/basic/messages.md @@ -4,8 +4,7 @@ type: docs weight: 20 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} All messages in MCP **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines diff --git a/docs/specification/2024-11-05/basic/transports.md b/docs/specification/2024-11-05/basic/transports.md index 192492ba4..6a222fd03 100644 --- a/docs/specification/2024-11-05/basic/transports.md +++ b/docs/specification/2024-11-05/basic/transports.md @@ -4,8 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} MCP currently defines two standard transport mechanisms for client-server communication: diff --git a/docs/specification/2024-11-05/basic/utilities/_index.md b/docs/specification/2024-11-05/basic/utilities/_index.md index 04ec76e6e..93e0a8b8a 100644 --- a/docs/specification/2024-11-05/basic/utilities/_index.md +++ b/docs/specification/2024-11-05/basic/utilities/_index.md @@ -2,8 +2,7 @@ title: Utilities --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} These optional features enhance the base protocol functionality with various utilities. diff --git a/docs/specification/2024-11-05/basic/utilities/cancellation.md b/docs/specification/2024-11-05/basic/utilities/cancellation.md index 879502189..9fa845285 100644 --- a/docs/specification/2024-11-05/basic/utilities/cancellation.md +++ b/docs/specification/2024-11-05/basic/utilities/cancellation.md @@ -3,8 +3,7 @@ title: Cancellation weight: 10 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) supports optional cancellation of in-progress requests through notification messages. Either side can send a cancellation notification to diff --git a/docs/specification/2024-11-05/basic/utilities/ping.md b/docs/specification/2024-11-05/basic/utilities/ping.md index 00aa47d85..b5aca29c4 100644 --- a/docs/specification/2024-11-05/basic/utilities/ping.md +++ b/docs/specification/2024-11-05/basic/utilities/ping.md @@ -3,8 +3,7 @@ title: Ping weight: 5 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol includes an optional ping mechanism that allows either party to verify that their counterpart is still responsive and the connection is alive. diff --git a/docs/specification/2024-11-05/basic/utilities/progress.md b/docs/specification/2024-11-05/basic/utilities/progress.md index 8381d8a7e..c3829b832 100644 --- a/docs/specification/2024-11-05/basic/utilities/progress.md +++ b/docs/specification/2024-11-05/basic/utilities/progress.md @@ -3,8 +3,7 @@ title: Progress weight: 30 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) supports optional progress tracking for long-running operations through notification messages. Either side can send progress notifications to diff --git a/docs/specification/2024-11-05/client/_index.md b/docs/specification/2024-11-05/client/_index.md index 09c94d929..7d31e5ae4 100644 --- a/docs/specification/2024-11-05/client/_index.md +++ b/docs/specification/2024-11-05/client/_index.md @@ -5,8 +5,7 @@ cascade: weight: 4 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} Clients can implement additional features to enrich connected MCP servers: diff --git a/docs/specification/2024-11-05/client/roots.md b/docs/specification/2024-11-05/client/roots.md index 878f9d50f..ea03b80c7 100644 --- a/docs/specification/2024-11-05/client/roots.md +++ b/docs/specification/2024-11-05/client/roots.md @@ -4,8 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for clients to expose filesystem "roots" to servers. Roots define the boundaries of where servers can operate diff --git a/docs/specification/2024-11-05/client/sampling.md b/docs/specification/2024-11-05/client/sampling.md index 6275b79ab..21f8ac6d6 100644 --- a/docs/specification/2024-11-05/client/sampling.md +++ b/docs/specification/2024-11-05/client/sampling.md @@ -4,8 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to request LLM sampling ("completions" or "generations") from language models via clients. This flow diff --git a/docs/specification/2024-11-05/revisions/2024-11-05.md b/docs/specification/2024-11-05/revisions/2024-11-05.md deleted file mode 100644 index 5ef43ab3f..000000000 --- a/docs/specification/2024-11-05/revisions/2024-11-05.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: 2024-11-05 (Current) -weight: 1 ---- - -This is the current version of the specification. This revision may continue to receive -backwards compatible changes. diff --git a/docs/specification/2024-11-05/revisions/_index.md b/docs/specification/2024-11-05/revisions/_index.md deleted file mode 100644 index 26f50e333..000000000 --- a/docs/specification/2024-11-05/revisions/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Revisions -cascade: - type: docs ---- - -This page lists the different revisions of the Model Context Protocol. See -[Versioning]({{< ref "/specification/2024-11-05/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/2024-11-05/basic/versioning" >}}). -- **Final**: past, complete specifications that will not be changed. diff --git a/docs/specification/2024-11-05/server/_index.md b/docs/specification/2024-11-05/server/_index.md index a60b72132..49d1fdff0 100644 --- a/docs/specification/2024-11-05/server/_index.md +++ b/docs/specification/2024-11-05/server/_index.md @@ -5,8 +5,7 @@ cascade: weight: 3 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable rich interactions between clients, servers, and language diff --git a/docs/specification/2024-11-05/server/prompts.md b/docs/specification/2024-11-05/server/prompts.md index f8dfc3a76..eac662c74 100644 --- a/docs/specification/2024-11-05/server/prompts.md +++ b/docs/specification/2024-11-05/server/prompts.md @@ -3,8 +3,7 @@ title: Prompts weight: 10 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt templates to clients. Prompts allow servers to provide structured messages and diff --git a/docs/specification/2024-11-05/server/resources.md b/docs/specification/2024-11-05/server/resources.md index 88ffc7ea2..4778b3576 100644 --- a/docs/specification/2024-11-05/server/resources.md +++ b/docs/specification/2024-11-05/server/resources.md @@ -4,8 +4,7 @@ type: docs weight: 20 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /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 diff --git a/docs/specification/2024-11-05/server/tools.md b/docs/specification/2024-11-05/server/tools.md index f635c8c13..39d30c530 100644 --- a/docs/specification/2024-11-05/server/tools.md +++ b/docs/specification/2024-11-05/server/tools.md @@ -4,8 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} 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 diff --git a/docs/specification/2024-11-05/server/utilities/_index.md b/docs/specification/2024-11-05/server/utilities/_index.md index 9ec69811a..fff13898e 100644 --- a/docs/specification/2024-11-05/server/utilities/_index.md +++ b/docs/specification/2024-11-05/server/utilities/_index.md @@ -2,8 +2,7 @@ title: Utilities --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} These optional features can be used to enhance server functionality. diff --git a/docs/specification/2024-11-05/server/utilities/completion.md b/docs/specification/2024-11-05/server/utilities/completion.md index 6277ece73..3c3cf4a77 100644 --- a/docs/specification/2024-11-05/server/utilities/completion.md +++ b/docs/specification/2024-11-05/server/utilities/completion.md @@ -2,8 +2,7 @@ title: Completion --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to offer argument autocompletion suggestions for prompts and resource URIs. This enables rich, diff --git a/docs/specification/2024-11-05/server/utilities/logging.md b/docs/specification/2024-11-05/server/utilities/logging.md index 67a3ec338..bf205e989 100644 --- a/docs/specification/2024-11-05/server/utilities/logging.md +++ b/docs/specification/2024-11-05/server/utilities/logging.md @@ -2,8 +2,7 @@ title: Logging --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to send structured log messages to clients. Clients can control logging verbosity by setting diff --git a/docs/specification/2024-11-05/server/utilities/pagination.md b/docs/specification/2024-11-05/server/utilities/pagination.md index 5c230eb0c..b436cea49 100644 --- a/docs/specification/2024-11-05/server/utilities/pagination.md +++ b/docs/specification/2024-11-05/server/utilities/pagination.md @@ -2,8 +2,7 @@ title: Pagination --- -{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}} -{{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}} The Model Context Protocol (MCP) supports paginating list operations that may return large result sets. Pagination allows servers to yield results in smaller chunks rather diff --git a/docs/specification/draft/_index.md b/docs/specification/2025-03-26/_index.md similarity index 96% rename from docs/specification/draft/_index.md rename to docs/specification/2025-03-26/_index.md index 14d6e4025..101c50dd2 100644 --- a/docs/specification/draft/_index.md +++ b/docs/specification/2025-03-26/_index.md @@ -1,14 +1,15 @@ --- -title: Specification (Draft) +linkTitle: 2025-03-26 (Latest) +title: Model Context Protocol specification cascade: type: docs breadcrumbs: false -weight: 10 +weight: 1 aliases: - - /draft + - /latest --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and diff --git a/docs/specification/draft/architecture/_index.md b/docs/specification/2025-03-26/architecture/_index.md similarity index 95% rename from docs/specification/draft/architecture/_index.md rename to docs/specification/2025-03-26/architecture/_index.md index 755e334fe..d94524755 100644 --- a/docs/specification/draft/architecture/_index.md +++ b/docs/specification/2025-03-26/architecture/_index.md @@ -2,7 +2,7 @@ title: Architecture cascade: type: docs -weight: 1 +weight: 10 --- The Model Context Protocol (MCP) follows a client-host-server architecture where each @@ -166,13 +166,13 @@ sequenceDiagram Each capability unlocks specific protocol features for use during the session. For example: -- Implemented [server features]({{< ref "/specification/draft/server" >}}) must be - advertised in the server's capabilities +- Implemented [server features]({{< ref "../server" >}}) must be advertised in the + server's capabilities - Emitting resource subscription notifications requires the server to declare subscription support - Tool invocation requires the server to declare tool capabilities -- [Sampling]({{< ref "/specification/draft/client" >}}) requires the client to declare - support in its capabilities +- [Sampling]({{< ref "../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. diff --git a/docs/specification/draft/basic/_index.md b/docs/specification/2025-03-26/basic/_index.md similarity index 89% rename from docs/specification/draft/basic/_index.md rename to docs/specification/2025-03-26/basic/_index.md index c5f8e93c3..7ab313963 100644 --- a/docs/specification/draft/basic/_index.md +++ b/docs/specification/2025-03-26/basic/_index.md @@ -2,10 +2,10 @@ title: Base Protocol cascade: type: docs -weight: 2 +weight: 20 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol consists of several key components that work together: @@ -103,10 +103,10 @@ batches, but **MUST** support receiving JSON-RPC batches. ## Auth -MCP provides an [Authorization]({{< ref "/specification/draft/basic/authorization" >}}) -framework for use with HTTP. Implementations using an HTTP-based transport **SHOULD** -conform to this specification, whereas implementations using STDIO transport **SHOULD -NOT** follow this specification, and instead retrieve credentials from the environment. +MCP provides an [Authorization]({{< ref "authorization" >}}) framework for use with HTTP. +Implementations using an HTTP-based transport **SHOULD** conform to this specification, +whereas implementations using STDIO transport **SHOULD NOT** follow this specification, +and instead retrieve credentials from the environment. Additionally, clients and servers **MAY** negotiate their own custom authentication and authorization strategies. diff --git a/docs/specification/draft/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md similarity index 98% rename from docs/specification/draft/basic/authorization.md rename to docs/specification/2025-03-26/basic/authorization.md index 76c433029..8270e182d 100644 --- a/docs/specification/draft/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -4,7 +4,7 @@ type: docs weight: 15 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} ## 1. Introduction @@ -136,8 +136,7 @@ domain hosting the MCP server, regardless of any path components in the MCP serv For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients **MUST** use the following default endpoint paths relative to the authorization base URL -(as defined in [Section -2.3.2]({{< ref "specification/draft/basic/authorization#232-authorization-base-url" >}})): +(as defined in [Section 2.3.2](#232-authorization-base-url)): | Endpoint | Default Path | Description | | ---------------------- | ------------ | ------------------------------------ | diff --git a/docs/specification/draft/basic/lifecycle.md b/docs/specification/2025-03-26/basic/lifecycle.md similarity index 83% rename from docs/specification/draft/basic/lifecycle.md rename to docs/specification/2025-03-26/basic/lifecycle.md index a98a2d3b9..47c6acded 100644 --- a/docs/specification/draft/basic/lifecycle.md +++ b/docs/specification/2025-03-26/basic/lifecycle.md @@ -4,7 +4,7 @@ type: docs weight: 30 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management. @@ -119,12 +119,12 @@ to indicate it is ready to begin normal operations: ``` - The client **SHOULD NOT** send requests other than - [pings]({{< ref "/specification/draft/basic/utilities/ping" >}}) before the server has - responded to the `initialize` request. + [pings]({{< ref "utilities/ping" >}}) before the server has responded to the + `initialize` request. - The server **SHOULD NOT** send requests other than - [pings]({{< ref "/specification/draft/basic/utilities/ping" >}}) and - [logging]({{< ref "/specification/draft/server/utilities/logging" >}}) before receiving - the `initialized` notification. + [pings]({{< ref "utilities/ping" >}}) and + [logging]({{< ref "../server/utilities/logging" >}}) before receiving the `initialized` + notification. #### Version Negotiation @@ -145,16 +145,16 @@ available during the session. Key capabilities include: -| Category | Capability | Description | -| -------- | -------------- | -------------------------------------------------------------------------------------------- | -| Client | `roots` | Ability to provide filesystem [roots]({{< ref "/specification/draft/client/roots" >}}) | -| Client | `sampling` | Support for LLM [sampling]({{< ref "/specification/draft/client/sampling" >}}) requests | -| Client | `experimental` | Describes support for non-standard experimental features | -| Server | `prompts` | Offers [prompt templates]({{< ref "/specification/draft/server/prompts" >}}) | -| Server | `resources` | Provides readable [resources]({{< ref "/specification/draft/server/resources" >}}) | -| Server | `tools` | Exposes callable [tools]({{< ref "/specification/draft/server/tools" >}}) | -| Server | `logging` | Emits structured [log messages]({{< ref "/specification/draft/server/utilities/logging" >}}) | -| Server | `experimental` | Describes support for non-standard experimental features | +| Category | Capability | Description | +| -------- | -------------- | -------------------------------------------------------------------------- | +| Client | `roots` | Ability to provide filesystem [roots]({{< ref "../client/roots" >}}) | +| Client | `sampling` | Support for LLM [sampling]({{< ref "../client/sampling" >}}) requests | +| Client | `experimental` | Describes support for non-standard experimental features | +| Server | `prompts` | Offers [prompt templates]({{< ref "../server/prompts" >}}) | +| Server | `resources` | Provides readable [resources]({{< ref "../server/resources" >}}) | +| Server | `tools` | Exposes callable [tools]({{< ref "../server/tools" >}}) | +| Server | `logging` | Emits structured [log messages]({{< ref "../server/utilities/logging" >}}) | +| Server | `experimental` | Describes support for non-standard experimental features | Capability objects can describe sub-capabilities like: @@ -180,8 +180,8 @@ mechanism should be used to signal connection termination: #### stdio -For the stdio [transport]({{< ref "/specification/draft/basic/transports" >}}), the -client **SHOULD** initiate shutdown by: +For the stdio [transport]({{< ref "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 @@ -193,8 +193,8 @@ exiting. #### HTTP -For HTTP [transports]({{< ref "/specification/draft/basic/transports" >}}), shutdown is -indicated by closing the associated HTTP connection(s). +For HTTP [transports]({{< ref "transports" >}}), shutdown is indicated by closing the +associated HTTP connection(s). ## Timeouts diff --git a/docs/specification/draft/basic/transports.md b/docs/specification/2025-03-26/basic/transports.md similarity index 99% rename from docs/specification/draft/basic/transports.md rename to docs/specification/2025-03-26/basic/transports.md index 9df0369b4..882a2a7ed 100644 --- a/docs/specification/draft/basic/transports.md +++ b/docs/specification/2025-03-26/basic/transports.md @@ -4,7 +4,7 @@ type: docs weight: 10 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded. diff --git a/docs/specification/draft/basic/utilities/_index.md b/docs/specification/2025-03-26/basic/utilities/_index.md similarity index 80% rename from docs/specification/draft/basic/utilities/_index.md rename to docs/specification/2025-03-26/basic/utilities/_index.md index f9a9bee2e..9def19bbf 100644 --- a/docs/specification/draft/basic/utilities/_index.md +++ b/docs/specification/2025-03-26/basic/utilities/_index.md @@ -2,7 +2,7 @@ title: Utilities --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} These optional features enhance the base protocol functionality with various utilities. diff --git a/docs/specification/draft/basic/utilities/cancellation.md b/docs/specification/2025-03-26/basic/utilities/cancellation.md similarity index 96% rename from docs/specification/draft/basic/utilities/cancellation.md rename to docs/specification/2025-03-26/basic/utilities/cancellation.md index d8e38d5a3..b99f24713 100644 --- a/docs/specification/draft/basic/utilities/cancellation.md +++ b/docs/specification/2025-03-26/basic/utilities/cancellation.md @@ -3,7 +3,7 @@ title: Cancellation weight: 10 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) supports optional cancellation of in-progress requests through notification messages. Either side can send a cancellation notification to diff --git a/docs/specification/draft/basic/utilities/ping.md b/docs/specification/2025-03-26/basic/utilities/ping.md similarity index 95% rename from docs/specification/draft/basic/utilities/ping.md rename to docs/specification/2025-03-26/basic/utilities/ping.md index ef1b1a78f..680596187 100644 --- a/docs/specification/draft/basic/utilities/ping.md +++ b/docs/specification/2025-03-26/basic/utilities/ping.md @@ -3,7 +3,7 @@ title: Ping weight: 5 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /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/draft/basic/utilities/progress.md b/docs/specification/2025-03-26/basic/utilities/progress.md similarity index 96% rename from docs/specification/draft/basic/utilities/progress.md rename to docs/specification/2025-03-26/basic/utilities/progress.md index 5bd135bbd..62a97f2c7 100644 --- a/docs/specification/draft/basic/utilities/progress.md +++ b/docs/specification/2025-03-26/basic/utilities/progress.md @@ -3,7 +3,7 @@ title: Progress weight: 30 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) supports optional progress tracking for long-running operations through notification messages. Either side can send progress notifications to diff --git a/docs/specification/2025-03-26/changelog.md b/docs/specification/2025-03-26/changelog.md new file mode 100644 index 000000000..430977ca2 --- /dev/null +++ b/docs/specification/2025-03-26/changelog.md @@ -0,0 +1,38 @@ +--- +title: Key Changes +type: docs +weight: 5 +--- + +This document lists changes made to the Model Context Protocol (MCP) specification since +the previous revision, [2024-11-05]({{< ref "../2024-11-05" >}}). + +## Major changes + +1. Added a comprehensive **[authorization framework]({{< ref "basic/authorization" >}})** + based on OAuth 2.1 (PR + [#133](https://github.com/modelcontextprotocol/specification/pull/133)) +1. Replaced the previous HTTP+SSE transport with a more flexible **[Streamable HTTP + transport]({{< ref "basic/transports#streamable-http" >}})** (PR + [#206](https://github.com/modelcontextprotocol/specification/pull/206)) +1. Added support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)** + (PR [#228](https://github.com/modelcontextprotocol/specification/pull/228)) +1. Added comprehensive **tool annotations** for better describing tool behavior, like + whether it is read-only or destructive (PR + [#185](https://github.com/modelcontextprotocol/specification/pull/185)) + +## Other schema changes + +- Added `message` field to `ProgressNotification` to provide descriptive status updates +- Added support for audio data, joining the existing text and image content types +- Added `completions` capability to explicitly indicate support for argument + autocompletion suggestions + +See +[the updated schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2025-03-26/schema.ts) +for more details. + +## Full changelog + +For a complete list of all changes that have been made since the last protocol revision, +[see GitHub](https://github.com/modelcontextprotocol/specification/compare/2024-11-05...2025-03-26). diff --git a/docs/specification/draft/client/_index.md b/docs/specification/2025-03-26/client/_index.md similarity index 75% rename from docs/specification/draft/client/_index.md rename to docs/specification/2025-03-26/client/_index.md index 8a64644b4..b1bcfd3de 100644 --- a/docs/specification/draft/client/_index.md +++ b/docs/specification/2025-03-26/client/_index.md @@ -2,10 +2,10 @@ title: Client Features cascade: type: docs -weight: 4 +weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} Clients can implement additional features to enrich connected MCP servers: diff --git a/docs/specification/draft/client/roots.md b/docs/specification/2025-03-26/client/roots.md similarity index 96% rename from docs/specification/draft/client/roots.md rename to docs/specification/2025-03-26/client/roots.md index 7cb1cf1cd..6f098a3cc 100644 --- a/docs/specification/draft/client/roots.md +++ b/docs/specification/2025-03-26/client/roots.md @@ -4,7 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /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 @@ -27,7 +27,7 @@ interaction model. ## Capabilities Clients that support roots **MUST** declare the `roots` capability during -[initialization]({{< ref "/specification/draft/basic/lifecycle#initialization" >}}): +[initialization]({{< ref "../basic/lifecycle#initialization" >}}): ```json { diff --git a/docs/specification/draft/client/sampling.md b/docs/specification/2025-03-26/client/sampling.md similarity index 98% rename from docs/specification/draft/client/sampling.md rename to docs/specification/2025-03-26/client/sampling.md index 6f968351f..bca9dfe39 100644 --- a/docs/specification/draft/client/sampling.md +++ b/docs/specification/2025-03-26/client/sampling.md @@ -4,7 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to request LLM sampling ("completions" or "generations") from language models via clients. This flow diff --git a/docs/specification/draft/server/_index.md b/docs/specification/2025-03-26/server/_index.md similarity index 94% rename from docs/specification/draft/server/_index.md rename to docs/specification/2025-03-26/server/_index.md index fb3411f51..d12acdfd9 100644 --- a/docs/specification/draft/server/_index.md +++ b/docs/specification/2025-03-26/server/_index.md @@ -2,10 +2,10 @@ title: Server Features cascade: type: docs -weight: 3 +weight: 30 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable rich interactions between clients, servers, and language diff --git a/docs/specification/draft/server/prompts.md b/docs/specification/2025-03-26/server/prompts.md similarity index 92% rename from docs/specification/draft/server/prompts.md rename to docs/specification/2025-03-26/server/prompts.md index 6deafe24b..568b7a670 100644 --- a/docs/specification/draft/server/prompts.md +++ b/docs/specification/2025-03-26/server/prompts.md @@ -3,7 +3,7 @@ title: Prompts weight: 10 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /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 @@ -29,17 +29,11 @@ model. ## Capabilities Servers that support prompts **MUST** declare the `prompts` capability during -[initialization]({{< ref "/specification/draft/basic/lifecycle#initialization" >}}): +[initialization]({{< ref "../basic/lifecycle#initialization" >}}): -```json -{ - "capabilities": { - "prompts": { - "listChanged": true - } - } -} -``` +/draft`json { "capabilities": { "prompts": { "listChanged": true } } } + +```` `listChanged` indicates whether the server will emit notifications when the list of available prompts changes. @@ -49,7 +43,7 @@ available prompts changes. ### Listing Prompts To retrieve available prompts, clients send a `prompts/list` request. This operation -supports [pagination]({{< ref "/specification/draft/server/utilities/pagination" >}}). +supports [pagination]({{< ref "utilities/pagination" >}}). **Request:** @@ -62,7 +56,7 @@ supports [pagination]({{< ref "/specification/draft/server/utilities/pagination" "cursor": "optional-cursor-value" } } -``` +```` **Response:** @@ -92,8 +86,7 @@ supports [pagination]({{< ref "/specification/draft/server/utilities/pagination" ### 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/draft/server/utilities/completion" >}}). +auto-completed through [the completion API]({{< ref "utilities/completion" >}}). **Request:** diff --git a/docs/specification/draft/server/resource-picker.png b/docs/specification/2025-03-26/server/resource-picker.png similarity index 100% rename from docs/specification/draft/server/resource-picker.png rename to docs/specification/2025-03-26/server/resource-picker.png diff --git a/docs/specification/draft/server/resources.md b/docs/specification/2025-03-26/server/resources.md similarity index 96% rename from docs/specification/draft/server/resources.md rename to docs/specification/2025-03-26/server/resources.md index a9e7bf7f7..0651e7c79 100644 --- a/docs/specification/draft/server/resources.md +++ b/docs/specification/2025-03-26/server/resources.md @@ -4,7 +4,7 @@ type: docs weight: 20 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /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 @@ -87,7 +87,7 @@ either, or both: ### Listing Resources To discover available resources, clients send a `resources/list` request. This operation -supports [pagination]({{< ref "/specification/draft/server/utilities/pagination" >}}). +supports [pagination]({{< ref "utilities/pagination" >}}). **Request:** @@ -161,8 +161,7 @@ To retrieve resource contents, clients send a `resources/read` request: 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/draft/server/utilities/completion" >}}). +auto-completed through [the completion API]({{< ref "utilities/completion" >}}). **Request:** diff --git a/docs/specification/draft/server/slash-command.png b/docs/specification/2025-03-26/server/slash-command.png similarity index 100% rename from docs/specification/draft/server/slash-command.png rename to docs/specification/2025-03-26/server/slash-command.png diff --git a/docs/specification/draft/server/tools.md b/docs/specification/2025-03-26/server/tools.md similarity index 94% rename from docs/specification/draft/server/tools.md rename to docs/specification/2025-03-26/server/tools.md index ba93e0523..dd7df7b94 100644 --- a/docs/specification/draft/server/tools.md +++ b/docs/specification/2025-03-26/server/tools.md @@ -4,7 +4,7 @@ type: docs weight: 40 --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} 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 @@ -53,7 +53,7 @@ available tools changes. ### Listing Tools To discover available tools, clients send a `tools/list` request. This operation supports -[pagination]({{< ref "/specification/draft/server/utilities/pagination" >}}). +[pagination]({{< ref "utilities/pagination" >}}). **Request:** @@ -221,9 +221,8 @@ Tool results can contain multiple content items of different types: #### Embedded Resources -[Resources]({{< ref "/specification/draft/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: +[Resources]({{< ref "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 { diff --git a/docs/specification/draft/server/utilities/_index.md b/docs/specification/2025-03-26/server/utilities/_index.md similarity index 80% rename from docs/specification/draft/server/utilities/_index.md rename to docs/specification/2025-03-26/server/utilities/_index.md index 449223dbf..747fc69e9 100644 --- a/docs/specification/draft/server/utilities/_index.md +++ b/docs/specification/2025-03-26/server/utilities/_index.md @@ -2,7 +2,7 @@ title: Utilities --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} These optional features can be used to enhance server functionality. diff --git a/docs/specification/draft/server/utilities/completion.md b/docs/specification/2025-03-26/server/utilities/completion.md similarity index 98% rename from docs/specification/draft/server/utilities/completion.md rename to docs/specification/2025-03-26/server/utilities/completion.md index 7e4ea4110..43e94976d 100644 --- a/docs/specification/draft/server/utilities/completion.md +++ b/docs/specification/2025-03-26/server/utilities/completion.md @@ -2,7 +2,7 @@ title: Completion --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) provides a standardized way for servers to offer argument autocompletion suggestions for prompts and resource URIs. This enables rich, diff --git a/docs/specification/draft/server/utilities/logging.md b/docs/specification/2025-03-26/server/utilities/logging.md similarity index 97% rename from docs/specification/draft/server/utilities/logging.md rename to docs/specification/2025-03-26/server/utilities/logging.md index 8e9f16837..d7531807d 100644 --- a/docs/specification/draft/server/utilities/logging.md +++ b/docs/specification/2025-03-26/server/utilities/logging.md @@ -2,7 +2,7 @@ title: Logging --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /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 diff --git a/docs/specification/draft/server/utilities/pagination.md b/docs/specification/2025-03-26/server/utilities/pagination.md similarity index 96% rename from docs/specification/draft/server/utilities/pagination.md rename to docs/specification/2025-03-26/server/utilities/pagination.md index 13efa23b9..db67ad74e 100644 --- a/docs/specification/draft/server/utilities/pagination.md +++ b/docs/specification/2025-03-26/server/utilities/pagination.md @@ -2,7 +2,7 @@ title: Pagination --- -{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} The Model Context Protocol (MCP) supports paginating list operations that may return large result sets. Pagination allows servers to yield results in smaller chunks rather diff --git a/docs/specification/_index.md b/docs/specification/_index.md index 14ae59f72..7e37c87a9 100644 --- a/docs/specification/_index.md +++ b/docs/specification/_index.md @@ -4,6 +4,4 @@ cascade: type: docs breadcrumbs: false weight: 10 -aliases: - - /latest --- diff --git a/docs/specification/2024-11-05/contributing/_index.md b/docs/specification/contributing.md similarity index 98% rename from docs/specification/2024-11-05/contributing/_index.md rename to docs/specification/contributing.md index 38a5951be..dee40e197 100644 --- a/docs/specification/2024-11-05/contributing/_index.md +++ b/docs/specification/contributing.md @@ -1,6 +1,6 @@ --- title: "Contributions" -weight: 10 +weight: 20 cascade: type: docs breadcrumbs: false diff --git a/docs/specification/draft/basic/versioning.md b/docs/specification/draft/basic/versioning.md deleted file mode 100644 index e2720692f..000000000 --- a/docs/specification/draft/basic/versioning.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Versioning -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 current protocol version is **draft**. [See all -revisions]({{< ref "/specification/draft/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. {{< /callout >}} - -Version negotiation happens during -[initialization]({{< ref "/specification/draft/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 to gracefully terminate connections when they cannot find a version compatible -with the server. diff --git a/docs/specification/draft/contributing/_index.md b/docs/specification/draft/contributing/_index.md deleted file mode 100644 index 38a5951be..000000000 --- a/docs/specification/draft/contributing/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Contributions" -weight: 10 -cascade: - type: docs -breadcrumbs: false ---- - -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 -[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions). diff --git a/docs/specification/draft/revisions/2024-11-05.md b/docs/specification/draft/revisions/2024-11-05.md deleted file mode 100644 index 5ef43ab3f..000000000 --- a/docs/specification/draft/revisions/2024-11-05.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: 2024-11-05 (Current) -weight: 1 ---- - -This is the current version of the specification. This revision may continue to receive -backwards compatible changes. diff --git a/docs/specification/draft/revisions/_index.md b/docs/specification/draft/revisions/_index.md deleted file mode 100644 index d1980cab8..000000000 --- a/docs/specification/draft/revisions/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Revisions -cascade: - type: docs ---- - -This page lists the different revisions of the Model Context Protocol. See -[Versioning]({{< ref "/specification/draft/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/draft/basic/versioning" >}}). -- **Final**: past, complete specifications that will not be changed. diff --git a/docs/specification/2024-11-05/basic/versioning.md b/docs/specification/versioning.md similarity index 51% rename from docs/specification/2024-11-05/basic/versioning.md rename to docs/specification/versioning.md index 81affa701..b0a1647bb 100644 --- a/docs/specification/2024-11-05/basic/versioning.md +++ b/docs/specification/versioning.md @@ -1,23 +1,33 @@ --- title: Versioning type: docs -weight: 80 +weight: 10 --- 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 >}}**. [See all -revisions]({{< ref "/specification/2024-11-05/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. {{< /callout >}} +## Revisions + +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. +- **Final**: past, complete specifications that will not be changed. + +The **current** protocol version is [**2025-03-26**]({{< ref "2025-03-26" >}}). + +## Negotiation + Version negotiation happens during -[initialization]({{< ref "/specification/2024-11-05/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. +[initialization]({{< ref "2025-03-26/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 to gracefully terminate connections when they cannot find a version compatible diff --git a/schema/draft/schema.json b/schema/2025-03-26/schema.json similarity index 100% rename from schema/draft/schema.json rename to schema/2025-03-26/schema.json diff --git a/schema/draft/schema.ts b/schema/2025-03-26/schema.ts similarity index 99% rename from schema/draft/schema.ts rename to schema/2025-03-26/schema.ts index b37469c0b..69c1f631a 100644 --- a/schema/draft/schema.ts +++ b/schema/2025-03-26/schema.ts @@ -21,7 +21,7 @@ export type JSONRPCBatchRequest = (JSONRPCRequest | JSONRPCNotification)[]; */ export type JSONRPCBatchResponse = (JSONRPCResponse | JSONRPCError)[]; -export const LATEST_PROTOCOL_VERSION = "DRAFT-2025-v1"; +export const LATEST_PROTOCOL_VERSION = "2025-03-26"; export const JSONRPC_VERSION = "2.0"; /** diff --git a/site/hugo.yaml b/site/hugo.yaml index c71daf815..d4caa720a 100644 --- a/site/hugo.yaml +++ b/site/hugo.yaml @@ -26,7 +26,6 @@ params: link: /latest width: 204 height: 30 - protocolRevision: "2024-11-05" markup: goldmark: @@ -58,21 +57,18 @@ enableInlineShortcodes: true menu: main: - - name: Specification (Draft) - pageRef: /draft - weight: 1 - - name: Specification (Latest) + - name: Specification pageRef: /latest - weight: 2 + weight: 1 - name: Resources pageRef: /resources - weight: 3 + weight: 2 - name: Search - weight: 4 + weight: 3 params: type: search - name: GitHub - weight: 5 + weight: 4 url: "https://github.com/modelcontextprotocol/specification" params: icon: github