Skip to content

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

Open

Description

@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

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

  1. added
    triageQueued for automated analysis — bot will process and remove this label
    on May 12, 2026
  2. ghost added
    bugSomething isn't working
    on May 12, 2026
  3. ghost added
    ready for workEnough information for someone to start working on
    on May 12, 2026
  4. ghost added
    authIssues and PRs related to Authentication / OAuth
    on May 12, 2026
  5. ghost added
    P2Moderate issues affecting some users, edge cases, potentially valuable feature
    on May 12, 2026
  6. ghost added
    fix proposedBot has a verified fix diff in the comment
    on May 12, 2026
  7. ghost removed
    triageQueued for automated analysis — bot will process and remove this label
    on May 12, 2026
  8. added a commit that references this issue on May 12, 2026
    02da247
  9. jshaofa-ui commented on May 16, 2026

    @jshaofa-ui
  10. serejaris commented on May 27, 2026

    @serejaris

    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.py
    • tests/client/test_auth.py

    And they all cover the two reported contracts:

    • refresh-token requests no longer include resource=;
    • bare-domain PRM resource URLs no longer retain Pydantic/AnyHttpUrl's trailing / in get_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.

  11. Marsssssssssssdsss commented on Jun 2, 2026

    @Marsssssssssssdsss
  12. whiskeysierra commented on Jun 2, 2026

    @whiskeysierra

    I posted anthropics/claude-code#52871 (comment) which explains a workaround

  13. fede-kamel commented on Jun 12, 2026

    @fede-kamel

    I'd like to pick this up. The maintainer-endorsed approach from #2590 — dropping resource from refresh_token grants 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 test tests/interaction/auth/test_lifecycle.py (added after #2590 was written) still snapshot-asserted the resource key in the refresh body, so it's updated there as well. Full local gate passes (100% coverage, strict-no-cover, ruff, pyright).

  14. added 2 commits that reference this issue on Aug 19, 2026
    e8afa1a
    1eef34d
  15. monkeydimi commented on Sep 24, 2026

    @monkeydimi

    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.

  16. will-bartlett commented on Oct 27, 2026

    @will-bartlett

    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).

    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.

  17. fede-kamel commented on Nov 16, 2026

    @fede-kamel

    @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 resource on refresh, as MCP requires. It only retries once without resource when the authorization server answers 400 with an error other than invalid_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?

  18. will-bartlett commented on Nov 17, 2026

    @will-bartlett

    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_grant is 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_grant is 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.

  19. fede-kamel commented on Nov 17, 2026

    @fede-kamel

    @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 resource based 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:

    >>> str(AnyHttpUrl("https://mcp.example.com"))
    'https://mcp.example.com/'

    get_resource_url() uses str(self.protected_resource_metadata.resource), so a server whose Protected Resource Metadata advertises "resource": "https://mcp.example.com" gets resource=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 is resource=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/ and https://mcp.example.com as 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:

    • drop the refresh retry entirely, so resource is always sent on refresh;
    • send the PRM resource exactly as the server published it, so no trailing slash is added to a bare origin, and keep the check_resource_allowed check as it is;
    • add a test with a bare-origin PRM resource, and a docs note linking the Entra guide for the configuration side.

    @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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Moderate issues affecting some users, edge cases, potentially valuable featureauthIssues and PRs related to Authentication / OAuthbugSomething isn't workingfix proposedBot has a verified fix diff in the commentready for workEnough information for someone to start working on

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions