[auth] Support new auth metadata endpoint from draft spec

[pcarleton]

The main change in this PR support for the protected resource metadata endpoint. Screenshots are below for a server with the endpoint and a server without it.

Some smaller changes related:

• Upgrade typescript sdk to v0.12.0
• Auth debugger tweaks
  • Got rid of the loading parameter in the auth debugger that wasn't useful
  • Started saving debugger state to SessionStorage so that the Quick Flow can persist state through redirecting to the Authorization server
    • this also allowed having the Quick Flow continue to completion post-redirect rather than waiting for user interaction
  • Added a new empty version of AuthDebuggerState to avoid having to update many places any time there's a new field
  • Added several fields to AuthDebuggerState to support the new metadata endpoint
  • got rid of defunct "nextStep" field in the Oauth state machine

Motivation and Context

This is to support the new auth step in the draft version of the spec.

How Has This Been Tested?

I added tests, and here are screenshots:

Breaking Changes

Non-breaking, if the endpoint isn't present, we'll fallback to the existing flow.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[olaservo]

Besides the build errors, main question is more related to the other PR that might cause conflicts, and whether it will handle session state correctly once there are multiple connections. Thinking this PR should go first since its an update to match the spec vs. a general improvement?

[pcarleton]

thanks @olaservo !

my bad on the failed build 😬 , I added a npm run lint to make it harder to miss next time.

re: session ID's, this all happens pre-MCP session initialization, so Cliff's PR should be independent.

[cliffhall]

@pcarleton I tested locally with the asana endpoint and the step where it handles metadata discovery looks good. A server that supports it would be nice to test against. That could be difficult to find at the moment, I realize.

Another thing I'm concerned about is the amount of errors now showing up in the test output. Is there a way we can get a handle on this output? Suppress it like this perhaps:

   beforeEach(() => {
     jest.spyOn(console, 'error').mockImplementation(() => {});
   });

   afterEach(() => {
     console.error.mockRestore();
   });

   test('my negative test', () => {
     // Your test code here, which might produce errors
   });

Screen.Recording.2025-06-02.at.5.17.47.PM.mov

[thedadams]

Hello! And thank you for this change.

I am using this branch to create MCP and auth server implementations that conform to the draft spec. Everything is working great except for one thing. I wanted to provide feedback in case it could be helpful.

The current implementation of the auth flow in this branch will register the client and construct the authorization URL using the supported_scopes from the oauth-authorization-server metadata. However, my understanding is that the auth server's metadata typically does not contain a complete list of all the supported scopes. In this case, it would be better if the client was registered and the authorization URL was constructed based on the supported_scopes from the oauth-protected-resource metadata served by the MCP server.

In my mind, this makes sense because the MCP server would be able to indicate which scopes it needs to perform its duties. Of course, please let me know if my understanding is out of line or my feedback is not helpful.

EDIT: From RFC8414 describing the oauth-authoriation-server metadata:

scopes_supported
      RECOMMENDED.  JSON array containing a list of the OAuth 2.0
      [[RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)] "scope" values that this authorization server supports.
      Servers MAY choose not to advertise some supported scope values
      even when this parameter is used.

[pcarleton]

@cliffhall thanks for testing! for an example that supports it, the typescript sdk server does here if you run it with --oauth:
https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/README.md#streamable-http-transport

npx tsx src/examples/server/simpleStreamableHttp.ts --oauth

@thedadams thanks for that. In practice, I expect folks to have the same value for supported scopes in both places, but I agree we should prefer the one in the protected resource metadata if it's available. I've changed it to prefer the scopes from that metadata.

edit: this discussion in springboot highlights another reason for preferring the protected-resource-metadata: the Authorization Server may list scopes that aren't valid for the resource since it may be shared across several resources. spring-projects/spring-security#8514

[thedadams]

Awesome, thanks! Does it make sense to use the scopes from the protected-resource-metadata for the authorization URL step as well?

[cliffhall]

@cliffhall thanks for testing! for an example that supports it, the typescript sdk server does here if you run it with --oauth: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/examples/README.md#streamable-http-transport

npx tsx src/examples/server/simpleStreamableHttp.ts --oauth

@pcarleton nice one! And much gratitude for the error output suppression in your tests!

I made sure my fork of the SDK was up to date and gave your example a try. It stopped at the token exchange step:

Interestingly, it seems like there may be some kind of looping hiccup because when I first tried to connect to the server, the url bar flashed for 5 seconds or so before settling down, like it was trying a url over and over. When I got the above issue, the console showed a rate limit error.

I cleared browser cache for the Inspector, restarted it and the AS/RS, and then I was able to make it through

[cliffhall]

Looking good except for the hook warning.

[cliffhall]

LGTM! 👍