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

[dasiths]

yeah I didn't include that path, do you think it will be useful?

[localden]

@dasiths great job with the diagram! This could be simplified further and be a bit more generic:

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: Credentials available<br/>User authorized with the MCP Server

    Client->>MCPServer: List primitives<br/>(Authorization header included)
    
    MCPServer->>PolicyEngine: Evaluate token for primitive access
    PolicyEngine-->>MCPServer: Return policy assessment
    
    MCPServer-->>Client: Return filtered primitive list

    Client->>MCPServer: Call primitive<br/>(Authorization header included)
    
    alt Token has required roles/scopes
        MCPServer->>PolicyEngine: Validate token for specific primitive access
        PolicyEngine-->>MCPServer: Return policy assessment
        MCPServer->>MCPServer: Invoke primitive
        MCPServer-->>Client: Return result
    else Token missing required permissions
        MCPServer->>PolicyEngine: Validate token for specific primitive access
        PolicyEngine-->>MCPServer: Recoverable state<br/>User needs extra scopes
        MCPServer-->>Client: HTTP 401 Unauthorized + WWW-Authenticate header
        Client-->>User: Bootstrap authorization flow with new scopes
        User->>AuthServer: Request additional scopes/roles
        AuthServer-->>User: Return updated JWT token
        Note over User, Client: Continue flow with new token
    end

Loading

[ggoodman]

To be sure, is it expected that the updated authorization requirements be encoded in the WWW-Authenticate header value (such as via scope requests)?

What is the user expected to do with the updated token? Isn't that token intended for the MCP Client (MCP Host, really)?

[dasiths]

To be sure, is it expected that the updated authorization requirements be encoded in the WWW-Authenticate header value (such as via scope requests)?

Yes.

What is the user expected to do with the updated token? Isn't that token intended for the MCP Client (MCP Host, really)?

The user here means the user-agent. The method/workflow for requesting additional scopes isn't specified in the draft doc. IMO it's beyond this spec and depends on the auth server used. Something to clarify though.

[DavidParks8]

What if a single tool changes its behavior based upon the scopes, but allows any combination of ~400 scopes? I don't believe that case is handled by the spec. Please correct me if I'm wrong.

[ayshsandu]

@kentcdodds
Here's a suggestion for a challenge-based mechanism to dynamically obtain permission. The MCP server can make the authorization decisions and discovery as well as at the primitive (ex: tool access) level.

1. If the server decides that authorization is required, and if there's no authentication or an invalid token is present, respond with a 401 Unauthorized status as currently specified. The WWW-Authenticate header can also include the required permission.
2. If the provided token lacks the necessary permission, the MCP server can respond with a 403 Forbidden status, including a challenge detailing the missing permissions, enabling the client to obtain a new, authorized token.

[dasiths]

One drawback of this approach is the lack of an authz aware ListTools() call. You wouldn't know what scopes are required till you try to use the tool. The draft Google Doc captures this in detail.

[ayshsandu]

@dasiths This flow complements the draft Google Doc.
And I agree that advertising the authorization requirements at the ListTools() is useful and important. The above suggestion is on-top of advertising authorization details in the tool definition and what you have suggested here for policy evaluation and enforcement.

An additional diff here is that, when the policy decision is that the token doesn't carry the required authorization, return a 403 Forbidded instead of 401, with a challenge to include the missing requirements. [ex:WWW-Authenticate: Bearer error="insufficient_scope" required_scope="scope1 scope2"

[nbarbettini]

Hi @kentcdodds, have you seen my spec proposal for an interaction_required error? I think it solves for many of the cases being discussed here. I agree completely that the protocol is missing this necessary "challenge" mechanism.

Specifically: how can the MCP server indicate to the MCP client that an additional action is required by the human end-user? This can be used for just-in-time authorization, step-up auth, etc.

[ggoodman]

I've proposed what I think might be a more generalized approach that solves problems like this. While I'm proposing it for tool calls, it may be more generally useful across other MCP resources.

PTAL: #405

[dasiths]

It doesn't capture a crucial detail which is the call to the "ListTools()" endpoint. The endpoint should only return tools available to the current auth scopes. The proposal doesn't address that.

[bdoyle0182]

^ this. doing this for the various list endpoints will make servers more scalable in terms of resources. Think of a generic mcp server abstraction that gives access to resources / prompts etc for a large org. You should only need to build one server for this, but the prompts / resources should be dynamic to the scopes you have access to so that when you connect to the server your client isn't attempting to load thousands and thousands of resources.

[nbarbettini]

@bdoyle0182 That's already possible today, no? With MCP authorization, the MCP server gets a token that identifies the user on every incoming request. The server implementation is free to dynamically change what artifacts are available based on who is connecting.

[DrewDennison]

I also would like this optional auth for my server (mcp.semgrep.ai), please let me know if I can help with any implementation work