Merge branch 'main' into session-hijack

Author: localden

docs/clients.mdx

@@ -35,7 +35,7 @@ This page provides an overview of applications that support the Model Context Pr
 | [Goose][Goose]                                   | ❌          | ❌        | ✅      | ❓                     | ❌         | ❌    | Supports tools.                                                                                 |
 | [gptme][gptme]                                   | ❌          | ❌        | ✅      | ❓                     | ❌         | ❌    | Supports tools.                                                                                 |
 | [HyperAgent][HyperAgent]                         | ❌          | ❌        | ✅      | ❓                     | ❌         | ❌    | Supports tools.                                                                                 |
-| [JetBrains AI Assistant][JetBrains AI Assistant] | ❌          | ❌        | ✅      | ❌                     | ❌         | ❌    | Supports tools for all JetBrains IDEs.                                                                                 |
+| [JetBrains AI Assistant][JetBrains AI Assistant] | ❌          | ❌        | ✅      | ❌                     | ❌         | ❌    | Supports tools for all JetBrains IDEs.                                                          |
 | [Klavis AI Slack/Discord/Web][Klavis AI]         | ✅          | ❌        | ✅      | ❓                     | ❌         | ❌    | Supports tools and resources.                                                                   |
 | [LibreChat][LibreChat]                           | ❌          | ❌        | ✅      | ❓                     | ❌         | ❌    | Supports tools for Agents                                                                       |
 | [Lutra][Lutra]                                   | ✅          | ✅        | ✅      | ❓                     | ❌         | ❌    | Supports any MCP server for reusable playbook creation.                                         |

docs/sdk/java/mcp-client.mdx

@@ -1,8 +1,10 @@
 ---
-title: MCP Client
+title: Java MCP Client
 description: Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
 ---
 
+Go to the [Java MCP Server](/sdk/java/mcp-server) to learn how to build MCP servers or the [Java MCP Overview](/sdk/java/mcp-overview) to understand the overall architecture.
+
 # Model Context Protocol Client
 
 The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
@@ -16,13 +18,17 @@ The MCP Client is a key component in the Model Context Protocol (MCP) architectu
 - Optional features like roots management and sampling support
 
 <Tip>
-
 The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO and SSE client transport implementations without requiring external web frameworks.
 
 Spring-specific transport implementations are available as an **optional** dependency `io.modelcontextprotocol.sdk:mcp-spring-webflux` for [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) users.
 
 </Tip>
 
+<Tip>
+  This [quickstart demo](/quickstart/client), based on Spring AI MCP, will show
+  you how to build an AI client that connects to MCP servers.
+</Tip>
+
 The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
 
 <Tabs>

docs/sdk/java/mcp-overview.mdx

@@ -1,19 +1,18 @@
 ---
-title: Overview
+title: Java SDK Overview
 description: Introduction to the Model Context Protocol (MCP) Java SDK
 ---
 
 Java SDK for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture)
 enables standardized integration between AI models and tools.
 
-<Note>
+## Content
 
-### Breaking Changes in 0.8.x ⚠️
-
-**Note:** Version 0.8.x introduces several breaking changes including a new session-based architecture.
-If you're upgrading from 0.7.0, please refer to the [Migration Guide](https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md) for detailed instructions.
-
-</Note>
+- [Introduction](/sdk/java/mcp-overview#features) - Overview of the Model Context Protocol (MCP) Java SDK and its features.
+  - [Architecture](/sdk/java/mcp-overview#architecture) - The Java MCP SDK architecture overview.
+  - [Java Dependencies](/sdk/java/mcp-overview#dependencies) - Java dependencies required to use the MCP SDK.
+- [Java MCP Client](/sdk/java/mcp-client) - Learn how to use the MCP client to interact with MCP servers.
+- [Java MCP Server](/sdk/java/mcp-server) - Learn how to implement and configure an MCP server.
 
 ## Features
 
@@ -55,12 +54,12 @@ The SDK follows a layered architecture with clear separation of concerns:
   - StdioTransport (stdin/stdout) in the core module
   - HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
 
-The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
+The [MCP Client](/sdk/java/mcp-client) is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
 It implements the client-side of the protocol.
 
 ![Java MCP Client Architecture](/images/java/java-mcp-client-architecture.jpg)
 
-The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
+The [MCP Server](/sdk/java/mcp-server) is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
 It implements the server-side of the protocol.
 
 ![Java MCP Server Architecture](/images/java/java-mcp-server-architecture.jpg)
@@ -154,7 +153,7 @@ Add the BOM to your project:
         <dependency>
             <groupId>io.modelcontextprotocol.sdk</groupId>
             <artifactId>mcp-bom</artifactId>
-            <version>0.9.0</version>
+            <version>0.10.0</version>
             <type>pom</type>
             <scope>import</scope>
         </dependency>
@@ -168,7 +167,7 @@ Add the BOM to your project:
 
 ```groovy
 dependencies {
-  implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.9.0")
+  implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.10.0")
   //...
 }
 ```

docs/sdk/java/mcp-server.mdx

@@ -1,16 +1,9 @@
 ---
-title: MCP Server
+title: Java MCP Server
 description: Learn how to implement and configure a Model Context Protocol (MCP) server
 ---
 
-<Note>
-
-### Breaking Changes in 0.8.x ⚠️
-
-**Note:** Version 0.8.x introduces several breaking changes including a new session-based architecture.
-If you're upgrading from 0.7.0, please refer to the [Migration Guide](https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md) for detailed instructions.
-
-</Note>
+Go to the [Java MCP Client](/sdk/java/mcp-client) to learn how to build MCP clients or [Java MCP Overview](/sdk/java/mcp-overview) for a general overview of the Model Context Protocol (MCP) in Java.
 
 ## Overview
 
@@ -32,6 +25,11 @@ Spring-specific transport implementations are available as an **optional** depen
 
 </Tip>
 
+<Tip>
+  This [quickstart demo](/quickstart/server), based on Spring AI MCP, will show
+  you how to build an MCP server.
+</Tip>
+
 The server supports both synchronous and asynchronous APIs, allowing for flexible integration in different application contexts.
 
 <Tabs>

docs/specification/draft/basic/authorization.mdx

@@ -178,19 +178,58 @@ sequenceDiagram
         A->>C: Client Credentials
     end
 
-    Note over C: Generate PKCE parameters
-    C->>B: Open browser with authorization URL + code_challenge
-    B->>A: Authorization request
+    Note over C: Generate PKCE parameters<br/>Include resource parameter
+    C->>B: Open browser with authorization URL + code_challenge + resource
+    B->>A: Authorization request with resource parameter
     Note over A: User authorizes
     A->>B: Redirect to callback with authorization code
     B->>C: Authorization code callback
-    C->>A: Token request + code_verifier
+    C->>A: Token request + code_verifier + resource
     A->>C: Access token (+ refresh token)
     C->>M: MCP request with access token
     M-->>C: MCP response
     Note over C,M: MCP communication continues with valid token
 ```
 
+#### Resource Parameter Implementation
+
+MCP clients **MUST** implement Resource Indicators for OAuth 2.0 as defined in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)
+to explicitly specify the target resource for which the token is being requested. The `resource` parameter:
+
+1. **MUST** be included in both authorization requests and token requests.
+2. **MUST** identify the MCP server that the client intends to use the token with.
+3. **MUST** use the canonical URI of the MCP server as defined in [RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#name-access-token-request).
+
+##### Canonical Server URI
+
+For the purposes of this specification, the canonical URI of an MCP server is defined as the resource identifier as specified in
+[RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2) and aligns with the `resource` parameter in
+[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).
+
+MCP clients **SHOULD** provide the most specific URI that they can for the MCP server they intend to access, following the guidance in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707). While the canonical form uses lowercase scheme and host components, implementations **SHOULD** accept uppercase scheme and host components for robustness and interoperability.
+
+Examples of valid canonical URIs:
+
+- `https://mcp.example.com/mcp`
+- `https://mcp.example.com`
+- `https://mcp.example.com:8443`
+- `https://mcp.example.com/server/mcp` (when path component is necessary to identify individual MCP server)
+
+Examples of invalid canonical URIs:
+
+- `mcp.example.com` (missing scheme)
+- `https://mcp.example.com#fragment` (contains fragment)
+
+> **Note:** While both `https://mcp.example.com/` (with trailing slash) and `https://mcp.example.com` (without trailing slash) are technically valid absolute URIs according to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986), implementations **SHOULD** consistently use the form without the trailing slash for better interoperability unless the trailing slash is semantically significant for the specific resource.
+
+For example, if accessing an MCP server at `https://mcp.example.com`, the authorization request would include:
+
+```
+&resource=https%3A%2F%2Fmcp.example.com
+```
+
+MCP clients **MUST** send this parameter regardless of whether authorization servers support it.
+
 ### Access Token Usage
 
 #### Token Requirements
@@ -214,7 +253,7 @@ even if they are part of the same logical session.
 Example request:
 
 ```http
-GET /v1/contexts HTTP/1.1
+GET /mcp HTTP/1.1
 Host: mcp.example.com
 Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 ```
@@ -223,6 +262,8 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 
 MCP servers, acting in their role as an OAuth 2.1 resource server, **MUST** validate access tokens as described in
 [OAuth 2.1 Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2).
+MCP servers **MUST** validate that access tokens were issued specifically for them as the intended audience,
+according to [RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2).
 If validation fails, servers **MUST** respond according to
 [OAuth 2.1 Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)
 error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401
@@ -313,8 +354,11 @@ MCP servers **MUST** validate access tokens before processing the request, ensur
 
 A MCP server **MUST** follow the guidelines in [OAuth 2.1 - Section 5.2](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-12.html#section-5.2) to validate inbound tokens.
 
-MCP servers **MUST** only accept tokens specifically intended for themselves.
+MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See [Security Best Practices Section 2.2](/specification/draft/basic/security_best_practices#token-passthrough) for details.
 
 If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a seperate token, issued by the upstream authorization server. The MCP server **MUST NOT** pass through the token it received from the MCP client.
 
-If the authorization server supports the `resource` parameter, it is recommended that implementers follow [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) to prevent token misuse.
+MCP clients **MUST** implement and use the `resource` parameter as defined in [RFC 8707 - Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html)
+to explicitly specify the target resource for which the token is being requested. This requirement aligns with the recommendation in
+[RFC 9728 Section 7.4](https://datatracker.ietf.org/doc/html/rfc9728#section-7.4). This ensures that access tokens are bound to their intended resources and
+cannot be misused across different services.

docs/specification/draft/basic/index.mdx

@@ -2,6 +2,8 @@
 title: Overview
 ---
 
+<div id="enable-section-numbers" />
+
 <Info>**Protocol Revision**: draft</Info>
 
 The Model Context Protocol consists of several key components that work together:
@@ -116,3 +118,29 @@ There is also a
 [JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.json),
 which is automatically generated from the TypeScript source of truth, for use with
 various automated tooling.
+
+### General fields
+
+#### `_meta`
+
+The `_meta` property/parameter is reserved by MCP to allow clients and servers
+to attach additional metadata to their interactions.
+
+Certain key names are reserved by MCP for protocol-level metadata, as specified below;
+implementations must not make assumptions about values at these keys.
+
+Additionally, definitions in the [schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts)
+may reserve particular names for purpose-specific metadata, as declared in those definitions.
+
+**Key name format:** valid `_meta` key names have two segments: an optional **prefix**, and a **name**.
+
+**Prefix:**
+
+- If specified, must be a series of labels separated by dots (`.`), followed by a slash (`/`).
+  - Labels must start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (`-`).
+- The `modelcontextprotocol.[*]/` and `mcp.[*]/` prefixes are reserved for MCP use (where `[*]` stands for any top-level domain).
+
+**Name:**
+
+- Unless empty, must begin and end with an alphanumeric character (`[a-z0-9A-Z]`).
+- Could contain hyphens (`-`), underscores (`_`), dots (`.`), and alphanumerics in between.

docs/specification/draft/server/utilities/completion.mdx

@@ -78,7 +78,7 @@ what is being completed through a reference type:
 }
 ```
 
-For prompts or URI templates with multiple arguments, clients should resolve them in the order they are presented by the server, and include each previous completion in the `context.arguments` object to provide context for subsequent requests.
+For prompts or URI templates with multiple arguments, clients should include previous completions in the `context.arguments` object to provide context for subsequent requests.
 
 **Request:**