OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)

[ShaneFlag]

Problem

The MCP Python SDK sends an RFC 8707 resource parameter on all token requests — including refresh_token grants. Microsoft Entra ID v2.0 rejects this with AADSTS9010010 (The resource parameter provided in the request doesn't match with the requested scopes).

This causes MCP servers using Entra ID OAuth to lose authentication after ~1 hour when the access token expires and the SDK attempts a silent refresh.

Root Cause

Two compounding issues:

1. Entra v2.0 does not support resource on refresh

Entra's v2.0 token endpoint expects scope, not resource. The resource parameter is a v1.0 concept. Since March 2026, Entra strictly validates and rejects resource on token refresh (previously it was silently ignored).

2. Pydantic v2 AnyHttpUrl trailing-slash normalization

ProtectedResourceMetadata.resource is typed as AnyHttpUrl (shared/auth.py:143). When str() is called on a bare-domain URL, Pydantic v2 adds a trailing slash:

>>> str(AnyHttpUrl("https://mcp-server.example.com"))
'https://mcp-server.example.com/'   # trailing slash added

In get_resource_url() (client/auth/oauth2.py:155), this trailing-slash version is used:

prm_resource = str(self.protected_resource_metadata.resource)  # adds trailing slash

But the Entra app registration has the audience as https://mcp-server.example.com (no slash), so the resource and scope audience don't match.

Affected Code

src/mcp/client/auth/oauth2.py:

async def _refresh_token(self) -> httpx.Request:
    refresh_data = {
        "grant_type": "refresh_token",
        "refresh_token": self.context.current_tokens.refresh_token,
        "client_id": self.context.client_info.client_id,
    }
    # This sends 'resource' on refresh — Entra v2.0 rejects it
    if self.context.should_include_resource_param(self.context.protocol_version):
        refresh_data["resource"] = self.context.get_resource_url()  # RFC 8707

The same issue exists in the TypeScript SDK (packages/client/src/client/auth.ts), where WHATWG URL also normalizes bare-domain URLs with a trailing slash.

Suggested Fix

Option A: Strip trailing slash in get_resource_url()

def get_resource_url(self) -> str:
    resource = resource_url_from_server_url(self.server_url)
    if self.protected_resource_metadata and self.protected_resource_metadata.resource:
        prm_resource = str(self.protected_resource_metadata.resource).rstrip('/')
        if check_resource_allowed(requested_resource=resource, configured_resource=prm_resource):
            resource = prm_resource
    return resource

Option B: Include scope alongside resource on refresh

Entra v2.0 tolerates resource if scope is also present and consistent:

refresh_data["scope"] = " ".join(self.context.scopes)

Option C: Make resource on refresh configurable

Allow servers to signal whether the resource parameter should be included on refresh grants, since not all authorization servers support RFC 8707.

Related Issues

• [BUG] MCP OAuth appends trailing slash to resource parameter, breaking Entra ID auth (AADSTS9010010) anthropics/claude-code#52871 — same trailing-slash + AADSTS9010010 bug
• [Bug]:Remote MCP server OAuth flow broken — AADSTS9010010: resource parameter conflicts with scope on v2.0 endpoint microsoft/powerbi-modeling-mcp#68 — same Entra v2.0 incompatibility

Environment

• MCP Python SDK: v1.27.0
• Authorization server: Microsoft Entra ID v2.0
• MCP server: Azure Container Apps with custom EntraTokenVerifier
• MCP spec version: 2025-06-18 (mandates RFC 8707 resource)

Current Workaround

Server-side: set resource_server_url=None in AuthSettings and do NOT serve /.well-known/oauth-protected-resource metadata. Without PRM, should_include_resource_param() returns False and resource is omitted from refresh requests. Initial auth still works via the WWW-Authenticate header fallback.

[mcp-claude]

two confirmed bugs: resource param sent on refresh_token grants (Entra v2.0 rejects with AADSTS9010010), and AnyHttpUrl adds a trailing slash to bare-domain resource URLs causing an audience mismatch.

workaround: don't serve /.well-known/oauth-protected-resource — without PRM, should_include_resource_param() returns False and resource is omitted from all requests including refresh.

repro script

"""
Repro for issue #2578:
1. AnyHttpUrl trailing slash normalization on bare-domain URLs
2. resource param included unconditionally in refresh_token requests
"""
import sys
import asyncio
import httpx
from unittest.mock import AsyncMock, MagicMock

sys.path.insert(0, "src")

from pydantic import AnyHttpUrl
from mcp.shared.auth import ProtectedResourceMetadata
from mcp.client.auth.oauth2 import OAuthContext, OAuthClientProvider
from mcp.shared.auth import OAuthClientInformationFull, OAuthToken


# ---- Bug 1: AnyHttpUrl trailing slash ----
bare_url = "https://mcp-server.example.com"
parsed = AnyHttpUrl(bare_url)
serialized = str(parsed)
print(f"[Bug 1] Input:      {bare_url!r}")
print(f"[Bug 1] str(AnyHttpUrl): {serialized!r}")
if serialized.endswith("/"):
    print("[Bug 1] REPRODUCED: trailing slash added by Pydantic v2")

# ---- Bug 1b: trailing slash flows into get_resource_url ----
prm = ProtectedResourceMetadata(
    resource=AnyHttpUrl(bare_url),
    authorization_servers=[AnyHttpUrl("https://login.microsoftonline.com/tenant/v2.0")],
)
prm_resource_str = str(prm.resource)
print(f"[Bug 1b] ProtectedResourceMetadata.resource: {prm_resource_str!r}")

# ---- Bug 2: resource param in refresh_token grant ----
storage = MagicMock()
storage.get_tokens = AsyncMock(return_value=None)
storage.set_tokens = AsyncMock()
storage.get_client_info = AsyncMock(return_value=None)
storage.set_client_info = AsyncMock()

client_info = OAuthClientInformationFull(
    client_id="test-client",
    client_secret="secret",
    redirect_uris=["http://localhost/callback"],
)
tokens = OAuthToken(
    access_token="old-access",
    token_type="bearer",
    refresh_token="old-refresh",
)

ctx = OAuthContext(
    server_url="https://mcp-server.example.com",
    client_metadata=MagicMock(redirect_uris=["http://localhost/callback"]),
    storage=storage,
    redirect_handler=AsyncMock(),
    callback_handler=AsyncMock(return_value=("code123", "state123")),
)
ctx.client_info = client_info
ctx.current_tokens = tokens
ctx.protected_resource_metadata = prm
ctx.protocol_version = "2025-06-18"

refresh_data = {
    "grant_type": "refresh_token",
    "refresh_token": ctx.current_tokens.refresh_token,
    "client_id": ctx.client_info.client_id,
}
if ctx.should_include_resource_param(ctx.protocol_version):
    refresh_data["resource"] = ctx.get_resource_url()

print(f"[Bug 2] refresh_token POST body: {refresh_data}")
if "resource" in refresh_data:
    print("[Bug 2] REPRODUCED: 'resource' param present in refresh_token grant")
    if refresh_data["resource"].endswith("/"):
        print("         (trailing slash — Entra audience mismatch)")

command + output

$ uv run python repro.py
[Bug 1] Input:      'https://mcp-server.example.com'
[Bug 1] str(AnyHttpUrl): 'https://mcp-server.example.com/'
[Bug 1] REPRODUCED: trailing slash added by Pydantic v2

[Bug 1b] ProtectedResourceMetadata.resource: 'https://mcp-server.example.com/'

[Bug 2] refresh_token POST body: {'grant_type': 'refresh_token', 'refresh_token': 'old-refresh', 'client_id': 'test-client', 'resource': 'https://mcp-server.example.com/'}
[Bug 2] REPRODUCED: 'resource' param present in refresh_token grant
         (trailing slash — Entra audience mismatch)

both bugs present on main (161834d) and v1.x (77431eb).

code path

Bug 1 — trailing slash: shared/auth.py:155 types ProtectedResourceMetadata.resource as AnyHttpUrl. Pydantic v2 normalizes bare-domain URLs by appending /. get_resource_url() at oauth2.py:154 calls str(self.protected_resource_metadata.resource) which returns the slash-suffixed form. Fix: call .rstrip('/') there, or change the field type to str with a URL validator.

Bug 2 — resource on refresh: _refresh_token() at oauth2.py:445-447 adds resource whenever should_include_resource_param() is true, with no exception for refresh_token grants. RFC 8707 doesn't mandate resource on refresh, and Entra v2.0 actively rejects it. Fix: remove lines 445-447 from _refresh_token, keeping resource only on the authorization redirect (oauth2.py:344-346) and initial token exchange (oauth2.py:400-402).

suggested fix

// src/mcp/client/auth/oauth2.py
-            prm_resource = str(self.protected_resource_metadata.resource)
+            prm_resource = str(self.protected_resource_metadata.resource).rstrip("/")
             if check_resource_allowed(requested_resource=resource, configured_resource=prm_resource):
                 resource = prm_resource

-        # Only include resource param if conditions are met
-        if self.context.should_include_resource_param(self.context.protocol_version):
-            refresh_data["resource"] = self.context.get_resource_url()  # RFC 8707
-
         # Prepare authentication based on preferred method

test to verify: test_get_resource_url_no_trailing_slash_for_bare_domain checks that get_resource_url() returns "https://mcp-server.example.com" (no trailing slash) when PRM resource is a bare-domain URL; test_refresh_token_excludes_resource_param confirms resource= is absent from the refresh POST body even when PRM is present and protocol version is 2025-06-18.