Merge branch 'main' of https://github.com/modelcontextprotocol/modelcontextprotocol

Author: olaservo

docs/docs/learn/client-concepts.mdx

@@ -108,7 +108,7 @@ Roots define filesystem boundaries for server operations, allowing clients to sp
 
 #### Overview
 
-Roots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. Rather than giving servers unrestricted filesystem access, roots guide them to relevant working directories. While roots communicate intended boundaries, actual security is always maintained by the client's access controls.
+Roots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. While roots communicate intended boundaries, they do not enforce security restrictions. Actual security must be enforced at the operating system level, via file permissions and/or sandboxing.
 
 **Root structure:**
 
@@ -139,7 +139,7 @@ For a complete implementation of a server that respects roots, see the [filesyst
 
 #### Design Philosophy
 
-Roots serve as a coordination mechanism between clients and servers, not a security boundary. The specification requires that servers "SHOULD respect root boundaries," and not that they "MUST enforce" them, because servers run code the client cannot control. This design is pragmatic: clients enforce security while roots communicate intent.
+Roots serve as a coordination mechanism between clients and servers, not a security boundary. The specification requires that servers "SHOULD respect root boundaries," and not that they "MUST enforce" them, because servers run code the client cannot control.
 
 Roots work best when servers are trusted or vetted, users understand their advisory nature, and the goal is preventing accidents rather than stopping malicious behavior. They excel at context scoping (telling servers where to focus), accident prevention (helping well-behaved servers stay in bounds), and workflow organization (such as managing project boundaries automatically).
 

docs/specification/draft/basic/security_best_practices.mdx

@@ -18,7 +18,7 @@ This section gives a detailed description of attacks on MCP implementations, alo
 
 ### Confused Deputy Problem
 
-Attackers can exploit MCP servers proxying other resource servers, creating "[confused deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem)" vulnerabilities.
+Attackers can exploit MCP proxy servers that connect to third-party APIs, creating "[confused deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem)" vulnerabilities. This attack allows malicious clients to obtain authorization codes without proper user consent by exploiting the combination of static client IDs, dynamic client registration, and consent cookies.
 
 #### Terminology
 
@@ -38,6 +38,15 @@ the third-party authorization server. This Client ID refers to the MCP server ac
 to the Third-Party API. It is the same value for all MCP server to Third-Party API interactions regardless of
 which MCP client initiated the request.
 
+#### Vulnerable Conditions
+
+This attack becomes possible when all of the following conditions are present:
+
+- MCP proxy server uses a **static client ID** with a third-party authorization server
+- MCP proxy server allows MCP clients to **dynamically register** (each getting their own client_id)
+- The third-party authorization server sets a **consent cookie** after the first authorization
+- MCP proxy server does not implement proper per-client consent before forwarding to third-party authorization
+
 #### Architecture and Attack Flows
 
 ##### Normal OAuth proxy usage (preserves user consent)
@@ -99,8 +108,7 @@ sequenceDiagram
 #### Attack Description
 
 When an MCP proxy server uses a static client ID to authenticate with a third-party
-authorization server that does not support dynamic client registration, the following
-attack becomes possible:
+authorization server, the following attack becomes possible:
 
 1. A user authenticates normally through the MCP proxy server to access the third-party API
 2. During this flow, the third-party authorization server sets a cookie on the user agent
@@ -114,8 +122,101 @@ attack becomes possible:
 
 #### Mitigation
 
-MCP proxy servers using static client IDs **MUST** obtain user consent for each dynamically
-registered client before forwarding to third-party authorization servers (which may require additional consent).
+To prevent confused deputy attacks, MCP proxy servers **MUST** implement per-client consent and proper security controls as detailed below.
+
+##### Consent Flow Implementation
+
+The following diagram shows how to properly implement per-client consent that runs **before** the third-party authorization flow:
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP Client
+    participant Browser as User's Browser
+    participant MCP as MCP Server
+    participant ThirdParty as Third-Party AuthZ Server
+
+    Note over Client,ThirdParty: 1. Client Registration (Dynamic)
+    Client->>MCP: Register with redirect_uri
+    MCP-->>Client: client_id
+
+    Note over Client,ThirdParty: 2. Authorization Request
+    Client->>Browser: Open MCP server authorization URL
+    Browser->>MCP: GET /authorize?client_id=...&redirect_uri=...
+
+    alt Check MCP Server Consent
+        MCP->>MCP: Check consent for this client_id
+        Note over MCP: Not previously approved
+    end
+
+    MCP->>Browser: Show MCP server-owned consent page
+    Note over Browser: "Allow [Client Name] to access [Third-Party API]?"
+    Browser->>MCP: POST /consent (approve)
+    MCP->>MCP: Store consent decision for client_id
+
+    Note over Client,ThirdParty: 3. Forward to Third-Party
+    MCP->>Browser: Redirect to third-party /authorize
+    Note over MCP: Use static client_id for third-party
+
+    Browser->>ThirdParty: Authorization request (static client_id)
+    ThirdParty->>Browser: User authenticates & consents
+    ThirdParty->>Browser: Redirect with auth code
+
+    Browser->>MCP: Callback with third-party code
+    MCP->>ThirdParty: Exchange code for token (using static client_id)
+    MCP->>Browser: Redirect to client's registered redirect_uri
+```
+
+##### Required Protections
+
+**Per-Client Consent Storage**
+
+MCP proxy servers **MUST**:
+
+- Maintain a registry of approved `client_id` values per user
+- Check this registry **before** initiating the third-party authorization flow
+- Store consent decisions securely (server-side database, or server specific cookies)
+
+**Consent UI Requirements**
+
+The MCP-level consent page **MUST**:
+
+- Clearly identify the requesting MCP client by name
+- Display the specific third-party API scopes being requested
+- Show the registered `redirect_uri` where tokens will be sent
+- Implement CSRF protection (e.g., state parameter, CSRF tokens)
+- Prevent iframing via `frame-ancestors` CSP directive or `X-Frame-Options: DENY` to prevent clickjacking
+
+**Consent Cookie Security**
+
+If using cookies to track consent decisions, they **MUST**:
+
+- Use `__Host-` prefix for cookie names
+- Set `Secure`, `HttpOnly`, and `SameSite=Lax` attributes
+- Be cryptographically signed or use server-side sessions
+- Bind to the specific `client_id` (not just "user has consented")
+
+**Redirect URI Validation**
+
+The MCP proxy server **MUST**:
+
+- Validate that the `redirect_uri` in authorization requests exactly matches the registered URI
+- Reject requests if the `redirect_uri` has changed without re-registration
+- Use exact string matching (not pattern matching or wildcards)
+
+**OAuth State Parameter Validation**
+
+The OAuth `state` parameter is critical to prevent authorization code interception and CSRF attacks. Proper state validation ensures that consent approval at the authorization endpoint is enforced at the callback endpoint.
+
+MCP proxy servers implementing OAuth flows **MUST**:
+
+- Generate a cryptographically secure random `state` value for each authorization request
+- Store the `state` value server-side (in a secure session store or encrypted cookie) **only after** consent has been explicitly approved
+- Set the `state` tracking cookie/session **immediately before** redirecting to the third-party identity provider (not before consent approval)
+- Validate at the callback endpoint that the `state` query parameter exactly matches the stored value in the callback request's cookies or in the request's cookie-based session
+- Reject any callback requests where the `state` parameter is missing or does not match
+- Ensure `state` values are single-use (delete after validation) and have a short expiration time (e.g., 10 minutes)
+
+The consent cookie or session containing the `state` value **MUST NOT** be set until **after** the user has approved the consent screen at the MCP server's authorization endpoint. Setting this cookie before consent approval renders the consent screen ineffective, as an attacker could bypass it by crafting a malicious authorization request.
 
 ### Token Passthrough