Merge branch 'main' into patch-1

Author: egoist

CONTRIBUTING.md

@@ -19,8 +19,8 @@ The following software is required to work on the spec:
 2. Clone your fork:
 
 ```bash
-git clone https://github.com/YOUR-USERNAME/specification.git
-cd specification
+git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
+cd modelcontextprotocol
 ```
 
 3. Install dependencies:

docs/clients.mdx

@@ -188,6 +188,7 @@
                   "specification/draft/basic/lifecycle",
                   "specification/draft/basic/transports",
                   "specification/draft/basic/authorization",
+                  "specification/draft/basic/security_best_practices",
                   {
                     "group": "Utilities",
                     "pages": [

docs/docs.json

@@ -42,6 +42,7 @@ These MCP servers are maintained by companies for their platforms:
 
 - **[Axiom](https://github.com/axiomhq/mcp-server-axiom)** - Query and analyze logs, traces, and event data using natural language
 - **[Browserbase](https://github.com/browserbase/mcp-server-browserbase)** - Automate browser interactions in the cloud
+- **[BrowserStack](https://github.com/browserstack/mcp-server)** - Access BrowserStack's [Test Platform](https://www.browserstack.com/test-platform) to debug, write and fix tests, do accessibility testing and more.
 - **[Cloudflare](https://github.com/cloudflare/mcp-server-cloudflare)** - Deploy and manage resources on the Cloudflare developer platform
 - **[E2B](https://github.com/e2b-dev/mcp-server)** - Execute code in secure cloud sandboxes
 - **[Neon](https://github.com/neondatabase/mcp-server-neon)** - Interact with the Neon serverless Postgres platform

docs/examples.mdx

@@ -39,6 +39,9 @@ source .venv/bin/activate
 uv add mcp anthropic python-dotenv
 
 # Remove boilerplate files
+# On Windows:
+del main.py
+# On Unix or MacOS:
 rm main.py
 
 # Create our main file

docs/quickstart/client.mdx

@@ -99,7 +99,6 @@ as described in OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatra
 
 MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
 
-
 #### 2.3.2 Server Metadata Discovery
 
 MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata protocol defined
@@ -247,17 +246,8 @@ own resources.
 
 MCP servers **MUST NOT** accept or transit any other tokens.
 
-### 2.8 Security Considerations
-
-The following security requirements **MUST** be implemented:
 
-1. Clients **MUST** securely store tokens following OAuth 2.0 best practices
-2. Servers **SHOULD** enforce token expiration and rotation
-3. All authorization endpoints **MUST** be served over HTTPS
-4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities
-5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs
-
-### 2.9 Error Handling
+### 2.8 Error Handling
 
 Servers **MUST** return appropriate HTTP status codes for authorization errors:
 
@@ -267,35 +257,50 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
 | 403         | Forbidden    | Invalid scopes or insufficient permissions |
 | 400         | Bad Request  | Malformed authorization request            |
 
-### 2.10 Implementation Requirements
+## 3. Security Considerations
+
+Implementations **MUST** follow OAuth 2.1 security best practices as laid out in [Section 7. Security Considerations](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#name-security-considerations).
+
+### 3.1 Token Theft
+Attackers who obtain tokens stored by the client, or tokens cached or logged on the server can access protected resources with
+requests that appear legitimate to resource servers.
+
+Clients **MUST** implement secure token storage and follow OAuth best practices,
+as outlined in [OAuth 2.1, section 7.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-7.1).
+
+MCP authorization servers SHOULD issue short-lived access tokens token to reduce the impact of leaked tokens. For public clients, MCP authorization servers MUST rotate refresh tokens as described in [Section 4.3.1 of OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-4.3.1).
+
+### 3.2 Communication Security
+Implementations MUST follow [OAuth 2.1 section 1.5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-1.5).
+
+Specifically:
+1. All authorization server endpoints **MUST** be served over HTTPS.
+1. All redirect URIs **MUST** be either `localhost` or use HTTPS.
+
+### 3.3 Authorization Code Protection
+
+An attacker who has gained access to an authorization code contained in an authorization response can try to redeem the authorization code for an access token or otherwise make use of the authorization code. (Further described in [OAuth 2.1, section 7.5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-7.5))
+
+MCP clients **MUST** implement PKCE according to [OAuth 2.1 section 7.5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-7.5.2). PKCE helps prevent authorization code interception and injection attacks by requiring clients to create a secret verifier-challenge pair, ensuring that only the original requestor can exchange an authorization code for tokens.
+
 
-1. Implementations **MUST** follow OAuth 2.1 security best practices
-1. PKCE is **REQUIRED** for all MCP clients and authorization servers
-1. MCP servers that also act as an AS:
-    1. **SHOULD** implement token rotation for enhanced security
-    1. **SHOULD** restrict token lifetimes based on security requirements
+### 3.3 Open Redirection
+An attacker may craft malicious redirect URIs to direct users to phishing sites.
 
-## 3. Best Practices
+MCP clients **MUST** have redirect URIs registered with the authorization server.
 
-#### 3.1 Local clients as Public OAuth 2.1 Clients
+Authorization servers **MUST** validate exact redirect URIs against pre-registered values to prevent redirection attacks.
 
-We strongly recommend that local clients implement OAuth 2.1 as a public client:
+MCP clients **SHOULD** use and verify state parameters in the authorization code flow
+and discard any results that do not include or have a mis-match with the original state.
 
-1. Utilizing code challenges (PKCE) for authorization requests to prevent interception
-   attacks
-2. Implementing secure token storage appropriate for the local system
-3. Following token refresh best practices to maintain sessions
-4. Properly handling token expiration and renewal
+Authorization servers **MUST** take precautions to prevent redirecting user agents to untrusted URI's, following suggestions laid out in [OAuth 2.1, Section 7.12.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-7.12.2)
 
-#### 3.2 Authorization Metadata Discovery
+Authorization servers **SHOULD** only automatically redirect the user agent if it trusts the redirection URI. If the URI is not trusted, the authorization server MAY inform the user and rely on the user to make the correct decision.
 
-We strongly recommend that all clients implement metadata discovery. This reduces the
-need for users to provide endpoints manually or clients to fallback to the defined
-defaults.
+### 3.4 Confused Deputy Problem
 
-#### 3.3 Dynamic Client Registration
+Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to confused deputy vulnerabilities. By using stolen authorization codes, they can obtain access tokens without user consent. See [Security Best Practices 2.1](/specification/draft/basic/security_best_practices) for details.
 
-Since clients do not know the set of MCP servers in advance, we strongly recommend the
-implementation of dynamic client registration. This allows applications to automatically
-register with the MCP server, and removes the need for users to obtain client ids
-manually.
+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).

docs/specification/draft/basic/authorization.mdx

@@ -0,0 +1,116 @@
+---
+title: Security Best Practices
+---
+
+## 1. Introduction
+
+### 1.1 Purpose and Scope
+
+This document provides security considerations for the Model Context Protocol (MCP), complementing the MCP Authorization specification. This document identifies security risks, attack vectors, and best practices specific to MCP implementations.
+
+The primary audience for this document includes developers implementing MCP authorization flows, MCP server operators, and security professionals evaluating MCP-based systems. This document should be read alongside the MCP Authorization specification and [OAuth 2.0 security best practices](https://datatracker.ietf.org/doc/html/rfc9700).
+
+## 2. Attacks and Mitigations
+
+This section gives a detailed description of attacks on MCP implementations, along with potential countermeasures.
+
+### 2.1 Confused Deputy Problem
+
+Attackers can exploit MCP servers proxying other resource servers, creating "[confused deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem)" vulnerabilities.
+
+#### 2.1.1 Terminology
+
+**MCP Proxy Server**
+: An MCP server that connects MCP clients to third-party APIs, offering MCP features while delegating operations and acting as a single OAuth client to the third-party API server.
+
+**Third-Party Authorization Server**
+: Authorization server that protects the third-party API. It may lack dynamic client registration support, requiring MCP proxy to use a static client ID for all requests.
+
+**Third-Party API**
+: The protected resource server that provides the actual API functionality. Access to this 
+  API requires tokens issued by the third-party authorization server.
+
+**Static Client ID**
+: A fixed OAuth 2.0 client identifier used by the MCP proxy server when communicating with
+  the third-party authorization server. This Client ID refers to the MCP server acting as a client
+  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.
+
+#### 2.1.2 Architecture and Attack Flows
+
+##### 2.1.2.1 Normal OAuth proxy usage (preserves user consent)
+
+```mermaid
+sequenceDiagram
+    participant UA as User-Agent (Browser)  
+    participant MC as MCP Client
+    participant M as MCP Proxy Server
+    participant TAS as Third-Party Authorization Server
+
+    Note over UA,M: Initial Auth flow completed
+
+    Note over UA,TAS: Step 1: Legitimate user consent for Third Party Server
+
+    M->>UA: Redirect to third party authorization server
+    UA->>TAS: Authorization request (client_id: mcp-proxy)
+    TAS->>UA: Authorization consent screen
+    Note over UA: Review consent screen
+    UA->>TAS: Approve
+    TAS->>UA: Set consent cookie for client ID: mcp-proxy
+    TAS->>UA: 3P Authorization code + redirect to mcp-proxy-server.com
+    UA->>M: 3P Authorization code
+    Note over M,TAS: Exchange 3P code for 3P token
+    Note over M: Generate MCP authorization code
+    M->>UA: Redirect to MCP Client with MCP authorization code
+
+    Note over M,UA: Exchange code for token, etc.
+```
+
+##### 2.1.2.3 Malicious OAuth proxy usage (skips user consent)
+
+```mermaid
+sequenceDiagram
+    participant UA as User-Agent (Browser)
+    participant M as MCP Proxy Server
+    participant TAS as Third-Party Authorization Server
+    participant A as Attacker
+
+
+    Note over UA,A: Step 2: Attack (leveraging existing cookie, skipping consent)
+    A->>M: Dynamically register malicious client, redirect_uri: attacker.com
+    A->>UA: Sends malicious link
+    UA->>TAS: Authorization request (client_id: mcp-proxy) + consent cookie
+    rect rgba(255, 17, 0, 0.67)
+    TAS->>TAS: Cookie present, consent skipped
+    end
+
+   TAS->>UA: 3P Authorization code + redirect to mcp-proxy-server.com
+   UA->>M: 3P Authorization code
+   Note over M,TAS: Exchange 3P code for 3P token
+   Note over M: Generate MCP authorization code
+   M->>UA: Redirect to attacker.com with MCP Authorization code
+   UA->>A: MCP Authorization code delivered to attacker.com
+   Note over M,A: Attacker exchanges MCP code for MCP token
+   A->>M: Attacker impersonates user to MCP server
+```
+
+#### 2.1.3 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:
+
+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
+   indicating consent for the static client ID
+3. An attacker later sends the user a malicious link containing a crafted authorization request which contains a malicious redirect URI along with a new dynamically registered client ID
+4. When the user clicks the link, their browser still has the consent cookie from the previous legitimate request
+5. The third-party authorization server detects the cookie and skips the consent screen
+6. The MCP authorization code is redirected to the attacker's server (specified in the crafted redirect_uri during dynamic client registration)
+7. The attacker exchanges the stolen authorization code for access tokens for the MCP server without the user's explicit approval
+8. Attacker now has access to the third-party API as the compromised user
+
+#### 2.1.4 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).

docs/specification/draft/basic/security_best_practices.mdx

@@ -24,9 +24,7 @@ In the **stdio** transport:
 - The client launches the MCP server as a subprocess.
 - The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages
   to its standard output (`stdout`).
-- Messages may be JSON-RPC requests, notifications, responses—or a JSON-RPC
-  [batch](https://www.jsonrpc.org/specification#batch) containing one or more requests
-  and/or notifications.
+- Messages are individual JSON-RPC requests, notifications, or responses.
 - 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.
@@ -85,35 +83,27 @@ MCP endpoint.
 1. The client **MUST** use HTTP POST to send JSON-RPC messages to the MCP endpoint.
 2. The client **MUST** include an `Accept` header, listing both `application/json` and
    `text/event-stream` as supported content types.
-3. The body of the POST request **MUST** be one of the following:
-   - A single JSON-RPC _request_, _notification_, or _response_
-   - An array [batching](https://www.jsonrpc.org/specification#batch) one or more
-     _requests and/or notifications_
-   - An array [batching](https://www.jsonrpc.org/specification#batch) one or more
-     _responses_
-4. If the input consists solely of (any number of) JSON-RPC _responses_ or
-   _notifications_:
+3. The body of the POST request **MUST** be a single JSON-RPC _request_, _notification_, or _response_.
+4. If the input is a JSON-RPC _response_ or _notification_:
    - If the server accepts the input, the server **MUST** return HTTP status code 202
      Accepted with no body.
    - If the server cannot accept the input, it **MUST** return an HTTP error status code
      (e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC _error
      response_ that has no `id`.
-5. If the input contains any number of JSON-RPC _requests_, the server **MUST** either
+5. If the input is a JSON-RPC _request_, the server **MUST** either
    return `Content-Type: text/event-stream`, to initiate an SSE stream, or
    `Content-Type: application/json`, to return one JSON object. The client **MUST**
    support both these cases.
 6. If the server initiates an SSE stream:
-   - The SSE stream **SHOULD** eventually include one JSON-RPC _response_ per each
-     JSON-RPC _request_ sent in the POST body. These _responses_ **MAY** be
-     [batched](https://www.jsonrpc.org/specification#batch).
-   - The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a
+   - The SSE stream **SHOULD** eventually include JSON-RPC _response_ for the
+     JSON-RPC _request_ sent in the POST body.
+   - The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending the
      JSON-RPC _response_. These messages **SHOULD** relate to the originating client
-     _request_. These _requests_ and _notifications_ **MAY** be
-     [batched](https://www.jsonrpc.org/specification#batch).
-   - The server **SHOULD NOT** close the SSE stream before sending a JSON-RPC _response_
-     per each received JSON-RPC _request_, unless the [session](#session-management)
+     _request_.
+   - The server **SHOULD NOT** close the SSE stream before sending the JSON-RPC _response_
+     for the received JSON-RPC _request_, unless the [session](#session-management)
      expires.
-   - After all JSON-RPC _responses_ have been sent, the server **SHOULD** close the SSE
+   - After the JSON-RPC _response_ has been sent, the server **SHOULD** close the SSE
      stream.
    - Disconnection **MAY** occur at any time (e.g., due to network conditions).
      Therefore:
@@ -133,9 +123,7 @@ MCP endpoint.
    this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server
    does not offer an SSE stream at this endpoint.
 4. If the server initiates an SSE stream:
-   - The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream. These
-     _requests_ and _notifications_ **MAY** be
-     [batched](https://www.jsonrpc.org/specification#batch).
+   - The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream.
    - These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC
      _request_ from the client.
    - The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**

docs/specification/draft/basic/transports.mdx

@@ -7,7 +7,9 @@ the previous revision, [2025-03-26](/specification/2025-03-26).
 
 ## Major changes
 
-1. TODO
+1. Removed support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)**
+   (PR [#416](https://github.com/modelcontextprotocol/specification/pull/416)) 
+2. TODO
 
 ## Other schema changes