René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Error \u0026 Mismatch in OAuth scope resolution between Claude.ai/MCP Python SDK and Inspector","articleBody":"### Initial Checks\n\n- [x] I confirm that I'm using the latest version of MCP Python SDK\n- [x] I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue\n\n### Description\n\n**TLDR:** The MCP Python SDK's OAuth flow and Claude.ai fetches scopes from the `.well-known/oauth-authorization-server` endpoint instead of the `.well-known/oauth-protected-resource` endpoint ([RFC-9728](https://datatracker.ietf.org/doc/html/rfc9728/)) causing Claude.ai connector authorization failures with MCP servers that have downscoped scoping permissions. \n\n_Working MCP Inspector Authorization Flow with correct scopes VS Failing Claude.ai connector with incorrect scopes_\n\n\u003cimg width=\"1046\" height=\"827\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/006ebdfa-9973-4dc7-8561-fe98beda8bdc\" /\u003e\n\n\u003cimg width=\"1005\" height=\"166\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/d3ee81af-62ba-419b-a9d4-093adc3c40d4\" /\u003e\n\nPer the [MCP Authorization spec](https://modelcontextprotocol.io/specification/draft/basic/authorization), the Claude client should start by fetching the (1) `.well-known/oauth-protected-resource endpoint` (per RFC-9728), which contains information about the authorization server and recommended scopes corresponding to that path. Currently, the MCP Python SDK only uses this endpoint to fetch the authorization server URL, but not the scopes. Instead, it fetches the scopes from the (2) `.well-known/oauth-authorization-server` metadata. In downscoped cases, this causes Claude to request incorrect scopes rather than the resource-specific scopes, resulting in `access_denied` during the auth callback stage.\n\nI noticed there is a discrepancy in this logic between the Python SDK implementation and the MCP Inspector Authorization flow walkthrough. The MCP Inspector correctly prioritizes scopes from the oauth-protected-resource metadata, falling back to the authorization server metadata only if no scopes are defined:\n```\n/**\n * Discovers OAuth scopes from server metadata, with preference for resource metadata scopes\n * @param serverUrl - The MCP server URL\n * @param resourceMetadata - Optional resource metadata containing preferred scopes\n * @returns Promise resolving to space-separated scope string or undefined\n */\nexport const discoverScopes = async (\n  serverUrl: string,\n  resourceMetadata?: OAuthProtectedResourceMetadata,\n): Promise\u003cstring | undefined\u003e =\u003e {\n  try {\n    const metadata = await discoverAuthorizationServerMetadata(\n      new URL(\"/\", serverUrl),\n    );\n\n    // Prefer resource metadata scopes, but fall back to OAuth metadata if empty\n    const resourceScopes = resourceMetadata?.scopes_supported;\n    const oauthScopes = metadata?.scopes_supported;\n\n    const scopesSupported =\n      resourceScopes \u0026\u0026 resourceScopes.length \u003e 0\n        ? resourceScopes\n        : oauthScopes;\n\n    return scopesSupported \u0026\u0026 scopesSupported.length \u003e 0\n      ? scopesSupported.join(\" \")\n      : undefined;\n  } catch (error) {\n    console.debug(\"OAuth scope discovery failed:\", error);\n    return undefined;\n  }\n};\n```\n\n**HOW TO REPRODUCE**\nI’ve validated this by updating the scopes being requested to the `/authorize` endpoint from Claude. \nI have set up an OAuth application that has a limited set of scopes, example:\n```\n\"scopes\": [\n        \"mcp.functions\",\n        \"offline_access\"\n    ],\n```\n\n_Failing flow_ (where scopes are retrieved from `.well-known/oauth-authorization-server` endpoint:\n```\nGET /oidc/v1/authorize?response_type=code\u0026client_id=910a86cd-07e2...\n**\u0026scope=all-apis+email+offline_access+openid+profile+sql**\n```\nCallback response looks something like:\n```\nhttps://claude.ai/api/mcp/auth_callback?error=access_denied\u0026error_description=Scopes+%27email+openid+profile%27+are+not+assigned+to+the+client\n```\n\nI then resubmitted the authorize request, but this time overrided the `scope` values to match that needed by our OAuth application (this follows the behavior in MCP Inspecotr):\n```\nGET /oidc/v1/authorize?response_type=code\u0026client_id=910a86cd-07e2...\n**\u0026scope=mcp.functions**\n```\nCallback response successfully returns an authorization code ✅ \n```\nhttps://claude.ai/api/mcp/auth_callback?code=dcod...\n```\n\nIn my setup, the first url (1) `.well-known/oauth-protected-resource endpoint` contains the proper set of scopes we need (in the `scopes_supported` field) while the second (2) `.well-known/oauth-authorization-server` endpoint advertises the list of all available scopes, but not for our particular resource. \n\n**THE ASK:**\nUpdate the scope requesting logic to be consistent with that in the MCP Inspector so the proper scopes are obtained during the authorization process. Otherwise, downscoping will not work properly with Claude connectors for MCP servers who rely on OAuth App connections for authentication/authorization.  This may look like: \n\t1.\tStore and apply scopes_supported from `.well-known/oauth-protected-resource` to the `authorize` endpoint.\n\t2.\tOnly fall back to `.well-known/oauth-authorization-server` if no scopes are present in the resource metadata.\n\n### Example Code\n\n```Python\n# From Python SDK in src/mcp/client/auth.py - we currently store authorization server information from the oauth protected resource endpoint but that's it:\n\nasync def _handle_protected_resource_response(self, response: httpx.Response) -\u003e None:\n    if response.status_code == 200:\n        content = await response.aread()\n        metadata = ProtectedResourceMetadata.model_validate_json(content)\n        self.context.protected_resource_metadata = metadata\n        if metadata.authorization_servers:\n            self.context.auth_server_url = str(metadata.authorization_servers[0])\n\n# Notice how there is no `scopes_supported` retrieved here.\n# Later, scopes are instead pulled from the authorization server metadata:\n\nasync def _handle_oauth_metadata_response(self, response: httpx.Response) -\u003e None:\n    content = await response.aread()\n    metadata = OAuthMetadata.model_validate_json(content)\n    self.context.oauth_metadata = metadata\n    if self.context.client_metadata.scope is None and metadata.scopes_supported is not None:\n        self.context.client_metadata.scope = \" \".join(metadata.scopes_supported)\n\n\n# Example Tentative Fix where we fetch scopes from the protected resource response:\n\n async def _handle_protected_resource_response(self, response: httpx.Response) -\u003e None:\n        \"\"\"Handle discovery response.\"\"\"\n        if response.status_code == 200:\n            try:\n                content = await response.aread()\n                metadata = ProtectedResourceMetadata.model_validate_json(content)\n                self.context.protected_resource_metadata = metadata\n                if metadata.authorization_servers:\n                    self.context.auth_server_url = str(metadata.authorization_servers[0])\n                \n                # Apply scopes from protected resource metadata if available\n                if (metadata.scopes_supported is not None):\n                    self.context.client_metadata.scope = \" \".join(metadata.scopes_supported)\n\n\n\n# Current logic from MCP Inspector in which authorization flow works:\n\n/**\n * Discovers OAuth scopes from server metadata, with preference for resource metadata scopes\n * @param serverUrl - The MCP server URL\n * @param resourceMetadata - Optional resource metadata containing preferred scopes\n * @returns Promise resolving to space-separated scope string or undefined\n */\nexport const discoverScopes = async (\n  serverUrl: string,\n  resourceMetadata?: OAuthProtectedResourceMetadata,\n): Promise\u003cstring | undefined\u003e =\u003e {\n  try {\n    const metadata = await discoverAuthorizationServerMetadata(\n      new URL(\"/\", serverUrl),\n    );\n\n    // Prefer resource metadata scopes, but fall back to OAuth metadata if empty\n    const resourceScopes = resourceMetadata?.scopes_supported;\n    const oauthScopes = metadata?.scopes_supported;\n\n    const scopesSupported =\n      resourceScopes \u0026\u0026 resourceScopes.length \u003e 0\n        ? resourceScopes\n        : oauthScopes;\n\n    return scopesSupported \u0026\u0026 scopesSupported.length \u003e 0\n      ? scopesSupported.join(\" \")\n      : undefined;\n  } catch (error) {\n    console.debug(\"OAuth scope discovery failed:\", error);\n    return undefined;\n  }\n};\n```\n\n### Python \u0026 MCP Python SDK\n\n```Text\nUsing Claude.ai site on 08/25/25\nMCP Python SDK: v1.13.1\n```","author":{"url":"https://github.com/jennsun","@type":"Person","name":"jennsun"},"datePublished":"2025-08-26T03:00:35.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/1307/python-sdk/issues/1307"}