Repository navigation
Description
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 addedIn get_resource_url() (client/auth/oauth2.py:155), this trailing-slash version is used:
prm_resource = str(self.protected_resource_metadata.resource) # adds trailing slashBut 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 8707The 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 resourceOption 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
resourceparameter, breaking Entra ID auth (AADSTS9010010) anthropics/claude-code#52871 — same trailing-slash + AADSTS9010010 bug - [Bug]:Remote MCP server OAuth flow broken — AADSTS9010010:
resourceparameter conflicts withscopeon 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.
Activity
fix: strip trailing slash from resource URL in get_resource_url()
jshaofa-ui commentedon May 16, 2026
serejaris commentedon May 27, 2026
Duplicate check update: I compared the three open linked PRs for this issue (#2590, #2645, and #2646).
All three touch the same focused surface:
src/mcp/client/auth/oauth2.pytests/client/test_auth.pyAnd they all cover the two reported contracts:
resource=;/inget_resource_url().I do not see an uncovered behavior that would justify another PR from my side. The useful next step looks like maintainer selection/consolidation of one of the existing PRs, not a new duplicate branch.
Marsssssssssssdsss commentedon Jun 2, 2026
whiskeysierra commentedon Jun 2, 2026
I posted anthropics/claude-code#52871 (comment) which explains a workaround
fede-kamel commentedon Jun 12, 2026
I'd like to pick this up. The maintainer-endorsed approach from #2590 — dropping
resourcefromrefresh_tokengrants and normalizing only root-path trailing slashes per RFC 9728's exact-identity requirement — was orphaned when that PR was closed during backlog cleanup without review.I've opened #2853 with a fresh implementation of that approach on current
main. One addition beyond #2590's scope: the newer interaction-level testtests/interaction/auth/test_lifecycle.py(added after #2590 was written) still snapshot-asserted theresourcekey in the refresh body, so it's updated there as well. Full local gate passes (100% coverage, strict-no-cover, ruff, pyright).Omit RFC 8707 resource param on refresh_token grants and strip root t…
Omit RFC 8707 resource param on refresh_token grants and strip root t…
monkeydimi commentedon Sep 24, 2026
Ciao ShaneFlag, ho letto il tuo report sul refresh OAuth MCP con Entra ID. Sto verificando come i team testano questi flussi prima del rilascio e se i test esistenti lasciano un problema pratico. Posso farti 4 domande brevi su come hai riprodotto il caso, quanto lavoro ha richiesto e se si è ripetuto? Non mi servono log, token o accesso ai sistemi; va bene anche rispondere qui, e nessun problema se non ti interessa.
will-bartlett commentedon Oct 27, 2026
This is not right. See https://learn.microsoft.com/en-us/entra/agent-id/secure-mcp-server-with-entra-id#step-3-set-the-application-id-uri-to-your-mcp-server-url. Entra validates and rejects or accepts resource on token refresh dependent on the resource configuration in Microsoft Entra. It should be sufficient for Python MCP users to provision their resource values on their Entra app registration.
I do recall there were some issues with trailing slash normalization in late 2025 / early 2026, but those should be resolved (on the Entra side) as well.
fede-kamel commentedon Nov 16, 2026
@maxisbey @Kludex could one of you assign this to me (CONTRIBUTING now asks for that before a PR)? Or tell me if you'd rather close it.
The fix is in #2853, which I just updated with main. All checks pass locally. Since @keeltrace's review it keeps
resourceon refresh, as MCP requires. It only retries once withoutresourcewhen the authorization server answers 400 with an error other thaninvalid_grant. A correctly configured server never takes that path.@will-bartlett, thanks for the pointer. If setting the Application ID URI to the MCP server URL fixes this for every Entra setup, the right fix may be documentation rather than code. In that case I'm happy to close #2853, or to turn it into a docs note linking that guide. Maintainers, which would you prefer?
will-bartlett commentedon Nov 17, 2026
My preference would be to close and rely on documentation. I would note that this issue predates that documentation page - we were getting a lot of questions of this nature before the documentation existed, but now that the documentation page exists, we are getting many fewer questions. That suggests to me that maybe this issue is perhaps already resolved.
I'm also not sure that retrying without resource on errors other than
invalid_grantis sufficiently secure. RFC 8707 is frustratingly non-prescriptive about error codes, writing e.g. "The following error code is provided", " It can also be used", "MAY fail requests that omit the parameter with an invalid_target error", "it should reject the request with an error response using the error code invalid_target" - but no MUST to be found. In my experience, OAuth implementations are frustratingly inconsistent about error codes outside of a few core scenarios.Finally, it's not clear to me that this PR actually solves any problem that still exists. RFC 8707 provides for the resource parameter on both the authorization and token endpoint requests, but the PR only specifies a fallback behavior for the token endpoint request (note that
invalid_grantis not a valid error code on authorization requests). While this fallback behavior may have been useful for Entra circa 2025, it's no longer useful for Entra (now that Entra has full support of RFC 8707), and it's not clear that it would be useful for any other OAuth Provider. Entra's peculiar behavior (invalid_request / AADSTS9010010) around the resource parameter in its v2 implementation can be traced directly to Entra's non-standard and pre-RFC 8707 v1 implementation that heavily relied upon a non-standard resource parameter that was given a different meaning than RFC 8707. I would not expect that any other OAuth Provider made exactly those same non-standard choices, and so it's not clear to me that #2853 would enable integration with any OAuth Provider that exists today.fede-kamel commentedon Nov 17, 2026
@will-bartlett thanks, that's a fair critique of the retry, and I agree with the main point. The spec says clients "MUST send this parameter regardless of whether authorization servers support it", and dropping
resourcebased on an error code no RFC pins down is the wrong trade. I'll take the retry out of #2853.I don't think the issue is fully resolved by documentation, though. The second root cause in the report is on the SDK side and is still on
main:get_resource_url()usesstr(self.protected_resource_metadata.resource), so a server whose Protected Resource Metadata advertises"resource": "https://mcp.example.com"getsresource=https://mcp.example.com/from the Python client. That's a different string from what the server published, and from the Application ID URI the Entra guide tells people to set. The spec's canonical URI section says implementations "SHOULD consistently use the form without the trailing slash", and its own example isresource=https%3A%2F%2Fmcp.example.com. The SDK currently does the opposite whenever the metadata resource is a bare origin.You mentioned Entra fixed its trailing-slash normalization. Does that mean Entra now treats
https://mcp.example.com/andhttps://mcp.example.comas the same resource on both authorization and refresh? If so, Entra users are covered. An authorization server that compares the string exactly, as RFC 8707 allows, would still reject or mis-scope the request, and the client created that mismatch itself.So my proposal is to narrow #2853 to that:
resourceis always sent on refresh;resourceexactly as the server published it, so no trailing slash is added to a bare origin, and keep thecheck_resource_allowedcheck as it is;@maxisbey @Kludex does that scope work for you? If you'd rather close the issue, I'll close #2853 and open a smaller PR for just the trailing-slash fix.