Server implementation of MCP auth

[jspahrsummers]

This implements the server side only of the MCP auth draft spec.

To do

• Authorization server metadata
• Dynamic client registration
• Use 405s for Method Not Allowed everywhere, including Allow header
• Update /authorize endpoint to check body for parameters in POST requests
• Authorization codes
• Strongly-typed error handling (e.g., to indicate that a scope is invalid)
• Token revocation API
• Catch exceptions from user code
• Access tokens
• Refresh tokens
• PKCE
• Direct integration with Express?
• Add auth requirement to MCP server endpoint(s)
• Add WWW-Authenticate header when bearer token auth fails
• Cache-Control header
• Tests
• Remove X-Powered-By header (this is done at the application level)
• Add rate limiting (h/t CodeQL)

Follow-ups

• Prevent refresh token replay
• Revoke tokens if authorization code presented a second time
• Make token revocation API a requirement?
• High-level convenience APIs for:
  • Becoming an authorization server directly (with pluggable storage)
  • Creating proxy tokens for a separate authorization server (with pluggable storage)
  • Passthrough proxying a separate authorization server
• Security considerations
  • Authorization servers MUST prevent clickjacking attacks. Multiple countermeasures are described in [RFC6819], including the use of the X-Frame-Options HTTP response header field and frame-busting JavaScript. In addition to those, authorization servers SHOULD also use Content Security Policy (CSP) level 2 [CSP-2] or greater.
  • Based on its risk assessment, the AS needs to decide whether it can trust the redirect URI or not. It could take into account URI analytics done internally or through some external service to evaluate the credibility and trustworthiness content behind the URI, and the source of the redirect URI and other client data.
  • The AS SHOULD only automatically redirect the user agent if it trusts the redirect URI. If the URI is not trusted, the AS MAY inform the user and rely on the user to make the correct decision.
  • Add iss parameter, per https://www.rfc-editor.org/rfc/rfc9207.html
  • Require 127.0.0.1 instead of localhost?
• Documentation & examples
• Rename authenticateClient to requireAuthedClient or similar

[jerome3o-anthropic]

This looks really good - I can't wait to cook with it.

One question regarding expired servers vs servers without secrets, the rest are non-blocking qns/comments

[jerome3o-anthropic]

[non-blocking] do we want this to be optional

[jspahrsummers]

Possibly… my main concern is really browser-based apps, but I think tree-shaking will ensure that none of Express makes it into those (it wouldn't be compatible anyway). I think it's pretty low-concern to have here, but willing to change it later if it becomes a problem.

[QuantGeekDev]

We should probably include CORS, or browser based clients won't be able to connect

[jerome3o-anthropic]

[non-blocking qn] explicitly disabled by setting configuration opens here?

[jspahrsummers]

Sorry, I don't understand the question. Can you rephrase?

[jerome3o-anthropic]

[non-blocking] if scopes are requested, but the client doesn't have any scopes (i.e. it's undefined), should we also throw an error? ig the client isn't concerned with scopes so it doesn't really matter what the client provides?

[jerome3o-anthropic]

oh also is "Invalid client_secret" correct for this error?

[jspahrsummers]

Yes, we should throw an error. Good catch.

Where do you see "invalid client_secret?"

[jerome3o-anthropic]

[non-blocking] is there not something pre-built for this?

[jspahrsummers]

Most of the logic is custom here. Only the header parsing bit conceivably might exist already, but it's so simple that it's probably not worth it.

[jerome3o-anthropic]

[non-blocking thought] is there room to do more for the server creator here? i.e. can we just have them make the "getToken"/"setToken" and we do the verification/expiry checks here?

[jerome3o-anthropic]

Claude thinks this could work:

interface SimplifiedOAuthProvider {
  // Token storage operations
  storeAuthorizationCode(userId: string, clientId: string, code: string, metadata: CodeMetadata): Promise<void>;
  fetchAuthorizationCode(code: string): Promise<CodeRecord | null>;
  deleteAuthorizationCode(code: string): Promise<void>;
  
  // Token operations
  storeToken(userId: string, clientId: string, tokenType: 'access'|'refresh', token: string, metadata: TokenMetadata): Promise<void>;
  fetchToken(token: string, tokenType: 'access'|'refresh'): Promise<TokenRecord | null>;
  deleteToken(token: string, tokenType: 'access'|'refresh'): Promise<void>;
  
  // User operations
  authenticateUser(req: Request, res: Response): Promise<string | null>; // Returns userId on success
  
  // Optional: Permission checking
  checkUserPermissions?(userId: string, clientId: string, scopes: string[]): Promise<boolean>;
}

But tbh we can add this later if needed

[jspahrsummers]

Yeah, let's tackle this later. I'm worried that this will actually be quite complex to make fully pluggable (e.g., for the auth proxying case too).

[jspahrsummers]

Thanks for the review! Will tackle the follow-ups in one or more other PRs, as this one has gotten big enough as it is.