Just-in-time auth flow

[kentcdodds]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Check this video demo.

I have a server where I classify tools/resources/prompts into three categories:

1. Public
2. Unauthenticated-only
3. Authenticated-only

These tools could probably be further broken down into authorization levels. Just like on websites where you show different UI to different users based on their auth, I think it makes sense to do the same for tools/resources/prompts. Because tools can be enabled/disabled via list_changed events, this is workable, however the current standard auth practice of this is either all or nothing. Either your server is fully locked down behind OAuth or it's not.

As a workaround for my server, I automatically approve all auth requests, and then have tools for users to provide their email address and have their auth session be associated to their account after validation code verification. It works ok, but it's not in the spirit of OAuth.

I'm not certain whether something needs to change in the spec or if there just needs to be more examples of servers that only lock down specific MCP method calls, but I believe that this practice will be common and would like to develop some kind of consensus on the way it is recommended to do this.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[ggoodman]

One possible avenue that comes to mind is to extend the set of error codes understood by MCP Clients to include one for authentication_required. An MCP Host that receives this sort of error should initiate the same authentication flow that is triggered by an initial 401 during connection.

This extension to the spec would allow for upgrading of an unauthenticated session to one that is authenticated. This flow would allow the MCP Host to capture and persist auth artifacts to maintain authentication across multiple sessions.

[kentcdodds]

In addition, an error code like insufficient_permissions, isufficient_authorization_scope or something could be useful (if such a thing is not already handled by another mechanism). This could trigger an auth flow for increasing the scope of the auth grant.

[localden]

This is good timing, @kentcdodds - one thing I was discussing at the MCP Developer Summit yesterday was tool authorization. I am working on a proposal that I will share later this coming week about what that would look like, but I believe it tackles the exact problem that you outlined here (what tools to expose when). The identity provider would be in charge of the policies (that the MCP server would have to help enforce), but there needs to be a standard way for expressing the tool availability.

[localden]

@kentcdodds take a look at the draft Google Doc for at some early thoughts.

[kentcdodds]

I just read through this and it's great. I'm pretty sure this will cover my use cases. I'm pretty much thinking of what would be required for MCP servers to completely replace the role websites/apps have today which means giving progressive and segmented access to different tools, resources, and prompts based on who is there. It appears this proposal does that. How can I help?

[localden]

@kentcdodds provide feedback and poke holes in the flow :) Also getting the word out and getting some input from as many people as possible would help a ton as this is being fleshed out, and before I open a PR to the spec (if one will be necessary, depending on the review).

[kentcdodds]

Some diagrams would help a great deal I think!

[dasiths]

@kentcdodds @localden Hope this helps.

sequenceDiagram
    participant User
    participant Client as MCP Client
    participant AuthServer as Authorization Server
    participant MCPServer as MCP Server
    participant PolicyEngine as Policy Engine

    Note over User, PolicyEngine: Authentication Phase
    User->>AuthServer: Authenticate (username/password, etc.)
    AuthServer->>User: Return JWT access token with roles/scopes

    Note over User, PolicyEngine: Discovery Phase
    User->>Client: Request available tools
    Client->>MCPServer: ListTools() with Authorization header
    Note right of Client: Bearer token included in request
    
    MCPServer->>PolicyEngine: Evaluate token for primitive access
    PolicyEngine->>MCPServer: Return accessible primitives list
    
    MCPServer->>Client: Return filtered tools with authorization metadata
    Note right of MCPServer: Only tools user can discover based on token
    
    Client->>User: Display available tools with required permissions
    Note left of Client: Shows tools and their role/scope requirements

    Note over User, PolicyEngine: Tool Invocation Phase
    User->>Client: Invoke specific tool (e.g., "create-file")
    Client->>MCPServer: Call tool with Authorization header + parameters
    
    alt Token has required roles/scopes
        MCPServer->>PolicyEngine: Validate token for specific tool
        PolicyEngine->>MCPServer: Authorization granted
        MCPServer->>MCPServer: Execute tool
        MCPServer->>Client: Return tool result
        Client->>User: Display success
    else Token missing required permissions
        MCPServer->>PolicyEngine: Validate token for specific tool
        PolicyEngine->>MCPServer: Authorization denied
        MCPServer->>Client: HTTP 401 Unauthorized + WWW-Authenticate header
        Note right of MCPServer: Includes required scopes/roles for re-auth
        Client->>User: Prompt for additional permissions
        User->>AuthServer: Request additional scopes/roles
        AuthServer->>User: Return updated JWT token
        Note over User, Client: Retry tool invocation with new token
    end

Loading