modelcontextprotocol
Oauth Support / Best practices
Add the hooks and utilities necessary to implement the OAuth aspects of the spec, including the OAuth resource server classification and client-side resource indicators added in the 6/18 version of the spec.
See https://github.com/modelcontextprotocol/go-sdk/issues/19#issuecomment-3352959772
is there an existing spec discussion on how we plan to implement this? would be happy to contribute if not already work in progress.
I have some work in progress. I should write a doc. Thanks for offering to help. I will probably get to this next week (Thursday and Friday are holidays).
@jba Quick check on oauth since you're already working on this.
I see you already have a PR on the .well-known endpoints. As part of the OAuth 2.1 spec implementation, I'd like to suggest a few considerations for the SDK:
Token Validation
- First-class support for validating tokens via JWKs (which you may already be considering)
- A custom validator interface, since tokens from external auth servers aren't always JWTs - they could be JWEs, custom strings/UUIDs, or other formats
- The custom validator pattern would also enable validation of custom headers beyond just bearer, technically not in scope, but could fall under the Authorization component if people implement non-standard secondary headers such as csrf or transactionID we should make it easy for them.
Client vs Server Flows Since this SDK supports both client and server modes, it would be valuable to consider:
- As a client: Bearer auth injection when making requests to downstream servers
- As a server: Passthrough OAuth 2.1 detection when go-sdk is a proxy for upstream requests
Let me know if this is scope creep for the current work - totally fine to push back. Otherwise, I'd be happy to take a crack at proposing some of these features.
I owe you a fuller response to this and on the other issue, but the idea is to use golang.org/x/oauth2, which hopefully has everything you're asking for. What's missing are the three extensions—Protected Resource Metadata, Auth Server Metadata, and Dynamic Client Registration—which we'll implement here.
We've mostly been thinking of it as client authorizing to MCP server, not passthrough. I think we should stick to what the MCP spec asks for first, before we consider any extensions. That is already a fair bit of work.
Since you seem to be pretty knowledgeable about this, are you interested in contributing? If not, that's fine. Feel free to file proposals for any features that go beyond the spec. But we probably won't get to them for a while, and we may choose not to provide them—that would depend a lot on how many people need them, how easy they are to work around, and so on.
Yeh I can lead this. I'll try and get a proposal out this weekend/early next week. And attach it here to bring in golang.org/x/oauth2. I do agree that spec-compatability should be the primary priority. Once I get peer reviews from more folks I can knock out a PR.
@jba Quick check on oauth since you're already working on this.
I see you already have a PR on the .well-known endpoints. As part of the OAuth 2.1 spec implementation, I'd like to suggest a few considerations for the SDK:
Token Validation
- First-class support for validating tokens via JWKs (which you may already be considering)
Do you mean JWTs? This is a server-side concern. I'm not sure that's in scope for an MCP SDK.
- A custom validator interface, since tokens from external auth servers aren't always JWTs - they could be JWEs, custom strings/UUIDs, or other formats
Why couldn't all validation be done inside the resource handler, which is supplied by the server author anyway? Perhaps one reason is that all details of the transport, like headers, are gone by that point.
- The custom validator pattern would also enable validation of custom headers beyond just bearer, technically not in scope, but could fall under the Authorization component if people implement non-standard secondary headers such as csrf or transactionID we should make it easy for them.
Perhaps StreamableServerTransportOptions should have a validator callback on it. We could give that the headers, or perhaps the entire http.Response. Would you like to file an issue about that?
Client vs Server Flows Since this SDK supports both client and server modes, it would be valuable to consider:
- As a client: Bearer auth injection when making requests to downstream servers
Can you elaborate what this means? #176 does bearer injection for the connected MCP server.
Let me know if this is scope creep for the current work - totally fine to push back. Otherwise, I'd be happy to take a crack at proposing some of these features.
I think that even if we ultimately decide that the server side is in scope, I want to finish the client side first. There are still open questions there.
Trying to summarize what is left for the 6-18 OAuth spec: (WIP, will update as I continue to audit the spec)
- [x] Extract resource_metadata from WWW-authenticate: WIP #544
- [ ] Enforce PKCE https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-code-protection
- [ ] Resource Parameter Implementation https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#resource-parameter-implementation
- [ ] A full working example of the authorization flow as shown in: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps [blocked by the previous issues]
- [ ] Standard JWT fields #512
- [ ] Default OAuth Handler
For the draft spec:
- [ ] OpenID discovery: https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-server-metadata-discovery
We can probably use some help from the community in completing this work. I will open issues as needed and mark them as help wanted.
Help wanted:
- [ ] #526
- [ ] #473
