Extensible protocol for tools to express unsatisfied preconditions

[ggoodman]

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

This document describes an extension to the Model Context Protocol (MCP) to handle scenarios where an MCP Server requires certain conditions to be met before a tool call can be successfully processed. This mechanism is generalizable to various types of preconditions.

Warning

This proposal is being withdrawn to focus efforts on modelcontextprotocol/modelcontextprotocol#475 whose goals and capabilities align with this.

Important

Added 2 Jun 2025 Everything in this proposal is negotiable except for these two key ideas:

1. A way to associate challenges (like the suggested AuthorizationRequired precondition) with the result of a tool call or other capability use. This lets the Host correlate the challenge with the failure.
2. A way for the MCP Server to update the Client on the outcome (ie: completion) of a challenge. In this proposal, I called it notifications/preconditions_met. The original challenge MUST have a unique identifier so that the MCP Server can reference in the original unmet precondition with the later notification that it was fulfilled.

These are the two novelties of this proposal that set it apart from ideas like Elicitation and modelcontextprotocol/modelcontextprotocol#45.

Extended Model Context Protocol Flow for Handling Preconditions

Introduction

This extension provides a generalizable mechanism for an MCP Server to signal to an MCP Host that a tool operation cannot be completed because certain preconditions are not met. It allows the MCP Server to describe these unmet preconditions. One common example, which will be used to illustrate the flow, is the AuthorizationRequired precondition, where the user might need to go through an OAuth2 authorization flow. Upon satisfaction of the precondition (e.g., successful authorization), the MCP Server notifies the MCP Host, which can then offer the user the option to retry the original tool call.

Participants

• User: The end-user interacting with the MCP Host application.
• MCP Host: The LLM application that initiates tool calls on behalf of the user. It interacts with the user and the MCP Server.
• MCP Server: The service providing tools. It may require certain preconditions to be met for operations and implements this protocol extension.
• Authorization Server (used in the AuthorizationRequired example): The OAuth2 provider for the third-party service the MCP Server needs to access.

Extended Protocol Elements

1. ToolCallResult Extension:
   The standard ToolCallResult from an MCP Server is extended with an optional field:

   • preconditions_failed (array, optional): A list of Precondition objects that were not met.

2. Precondition Object:
   Describes a single unmet precondition. It has a general structure:

   • type (string): A string identifying the kind of precondition. Examples include "AuthorizationRequired", "PaymentRequired", "TermsOfServiceAgreementNeeded", etc.
   • preconditionId (string): A unique identifier for this specific precondition instance. This ID is used by the MCP Server to later notify the MCP Host that the precondition has been satisfied.
   • metadata (object): An object containing data specific to the type of precondition, providing information needed to resolve it.

   Example Precondition Type: AuthorizationRequired
   This specific type indicates that the MCP Server needs the user to authorize it, typically via OAuth2.

   • type: MUST be "AuthorizationRequired".
   • preconditionId: A unique identifier for this authorization request.
   • metadata: For AuthorizationRequired, this object would contain:
     • authorizationUrl (string): The URL the user should be directed to for initiating the OAuth2 authorization code flow (e.g., https://auth.example.com/authorize?...). This URL itself MUST encode all necessary OAuth2 parameters required by the Authorization Server, including client_id, response_type=code, scope, the MCP Server's redirect_uri, state, and PKCE parameters (code_challenge, code_challenge_method).
     • requestedScopes (array of strings, optional): A list of scopes the MCP Server is requesting. This can be useful for the MCP Host to display to the user, even if also encoded within the authorizationUrl.

3. New Notification: notifications/preconditions_satisfied:
   A new notification sent by the MCP Server to the MCP Host.

   • method: "notifications/preconditions_satisfied"
   • params: (object)
     • preconditionId (string): The unique identifier of the Precondition (from the preconditionId field of the object in the preconditions_failed array) that has now been satisfied.

Interaction Flow (Illustrated with AuthorizationRequired Precondition)

The following steps describe the interaction, using the AuthorizationRequired precondition as an example:

1. Tool Invocation: The MCP Host, on behalf of an authenticated user, invokes a tool on the MCP Server.

2. Precondition Check by Server: The MCP Server's tool handler logic determines that one or more preconditions are not met. In this example, it lacks the necessary user credentials for a third-party service.

3. Server Responds with preconditions_failed: The MCP Server returns a ToolCallResult. This result indicates the immediate tool call failed or cannot proceed and includes the preconditions_failed field. For this example, this field contains an AuthorizationRequired object with a unique preconditionId and the authorizationUrl.

   Example ToolCallResult snippet for AuthorizationRequired:

   {
     "jsonrpc": "2.0",
     "id": "tool_call_request_id_123",
     "result": {
       "content": [{ "type": "text", "text": "Action requires further authorization." }],
       "isError": true, // Or false, depends on signaling for the primary action
       "preconditions_failed": [
         {
           "type": "AuthorizationRequired",
           "preconditionId": "auth_req_abc789",
           "metadata": {
             "authorizationUrl": "https://auth.example.com/authorize?response_type=code&client_id=mcp_server_client&redirect_uri=https%3A%2F%2Fmcp.server.com%2Foauth%2Fcallback&scope=read%3Adata&code_challenge=...",
             "requestedScopes": ["read:data"]
           }
         }
       ]
     }
   }

4. Host Prompts User: The MCP Host processes the preconditions_failed response. If it understands the AuthorizationRequired type (or other precondition types), it presents an appropriate interface to the user. For AuthorizationRequired, it explains that authorization is needed and provides a link (using the authorizationUrl) to grant permissions to the MCP Server.

5. User Authorizes (OAuth2 Flow for AuthorizationRequired example): The User clicks the link. This initiates the standard OAuth2 authorization code grant flow with PKCE:
   a. User is redirected to the Authorization Server's authorizationUrl.
   b. User authenticates and grants consent on the Authorization Server.
   c. Authorization Server redirects the User back to the MCP Server's redirect_uri (which was encoded within the authorizationUrl) with an authorization code.

6. MCP Server Handles OAuth Callback (for AuthorizationRequired example): The MCP Server's callback handler:
   a. Receives the authorization code and retrieves the PKCE code_verifier.
   b. Exchanges the code and code_verifier for an Access Token (and optionally a Refresh Token) from the Authorization Server.
   c. Securely stores the obtained token(s), associating them with the user's MCP session or user identity on the MCP Server. This satisfies the AuthorizationRequired precondition.

7. Server Notifies Host of Satisfaction: After the precondition is satisfied (e.g., successfully obtaining and storing credentials), the MCP Server sends a notifications/preconditions_satisfied message to the MCP Host. This notification includes the preconditionId from the original Precondition object.

   Example notifications/preconditions_satisfied message:

   {
     "jsonrpc": "2.0",
     "method": "notifications/preconditions_satisfied",
     "params": {
       "preconditionId": "auth_req_abc789"
     }
   }

8. Host Offers Retry: The MCP Host receives this notification. If the context is still relevant and the Host is not otherwise busy with a conflicting operation, it may present the user with an option to retry the original tool call that previously encountered the unmet precondition.

9. User Opts to Retry, Host Re-invokes Tool: If the user chooses to retry, the MCP Host uses its MCP Client to invoke the same tool again on the MCP Server.

10. Server Completes Operation: The MCP Server now finds that the previously unmet precondition is satisfied (e.g., it has the necessary stored credentials). It successfully executes the tool's business logic.

11. Host Receives Successful Outcome: The MCP Server returns a successful ToolCallResult to the MCP Host, and the Host presents the outcome to the user.

Note on Subsequent Calls: For the AuthorizationRequired example, subsequent tool calls from the same user that require the same third-party credentials can leverage this pre-existing delegation of authorization without repeating the OAuth2 flow, as long as the stored tokens are valid and cover the required scopes. Similar logic would apply to other types of satisfied preconditions.

Sequence Diagram (Illustrating AuthorizationRequired Precondition Flow)

sequenceDiagram
    participant User
    participant MCP Host
    participant MCP Server
    participant Authorization Server

    MCP Host->>MCP Server: 1. Tool Call Request (on behalf of User)
    Note over MCP Server: 2. Business logic determines `AuthorizationRequired` precondition is not met
    MCP Server->>MCP Host: 3. Tool Call Response (with `preconditions_failed` [`type: "AuthorizationRequired"`, `preconditionId`, `authorizationUrl`])
    MCP Host->>User: 4. Prompt User to authorize (presents link with `authorizationUrl`)

    User->>Authorization Server: 5a. Clicks link, navigates to `authorizationUrl`
    Authorization Server-->>User: 5b. Prompts for login & consent
    User->>Authorization Server: 5c. User logs in & grants consent
    Authorization Server-->>User: 5d. Redirects to MCP Server's `redirectUri` (from `authorizationUrl`) with auth `code`

    User->>MCP Server: 6a. Request to MCP Server's `redirectUri` (contains auth `code`)
    MCP Server->>Authorization Server: 6b. Exchange auth `code` + PKCE verifier for Access Token
    Authorization Server->>MCP Server: 6c. Access Token (+ Refresh Token)
    Note over MCP Server: 6d. Stores token. `AuthorizationRequired` precondition (`preconditionId`) is now satisfied.

    MCP Server->>MCP Host: 7. `notifications/preconditions_satisfied` (with `preconditionId`)
    MCP Host->>User: 8. Offer User option to retry original tool call
    User->>MCP Host: (User confirms retry)
    MCP Host->>MCP Server: 9. Re-try Tool Call Request
    Note over MCP Server: 10. Precondition satisfied (has credentials), performs operation.
    MCP Server->>MCP Host: 11. Tool Call Response (Success)
    MCP Host->>User: (Presents successful outcome)

Loading

Scope

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

[dasiths]

With regards to this...

        "metadata": {
          "authorizationUrl": "https://auth.example.com/authorize?response_type=code&client_id=mcp_server_client&redirect_uri=https%3A%2F%2Fmcp.server.com%2Foauth%2Fcallback&scope=read%3Adata&code_challenge=...",
          "requestedScopes": ["read:data"]
        }

I don't think the meatadata should have the "auth url". If at all just point to the PRM endpoint. We don't want multiple discovery mechanism for auth in the spec. Just the scopes are enough IMO. We assume the client already knows how to authenticate and ask for extra scopes.

[ggoodman]

I'm wondering whether we can't use it to describe all associated resources. A mapping of sorts.

I'm not a huge fan of this. The privilege level of the user of the MCP Server will change over time and potentially even within the lifetime of a single MCP Session. It seems like any attempt to encode this in the PRM forces all of this to be known and encoded up front. I don't think a dynamic system like this can support that.

I also don't really understand why the MCP Host should have to know about the downstream resources at all.

[dasiths]

I'm thinking of this from a governance perspective. As an admin, do you want the users of your app (MCP client) being asked to authenticate against any AS? Similarly with resources. I don't know the answers but have a hunch that letting the MCP server dynamically determining where to redirect the user for auth might not be desirable. I don't even know if PRM is extensible but if it is, at least you can take action as an admin when it changes. I'm following the conversation in #475 to see how it evolves too.

I think a model like this might be better suited for enterprise use cases. Which gives a better user experience as well. https://aaronparecki.com/2025/05/12/27/enterprise-ready-mcp#cross-app-access-protocol

[wdawson]

@dasiths totally agree with what Aaron proposes as the ideal way to do the auth piece! And also agree with the risks of essentially providing an open redirect server.

However, I think we're a ways away from the industry adopting the standards that Aaron relies on in that proposal:

• in-progress OAuth specification "Identity and Authorization Chaining Across Domains"
• Token Exchange (RFC 8693)
• JWT Profile for Authorization Grants (RFC 7523)

modelcontextprotocol/modelcontextprotocol#475 tries to meet the industry where it is without sacrificing security. There are notable UX downsides to this, and we hope that adopting 475 will help increase the adoption of those specs above to provide a better experience and maintain the security landscape.

[wdawson]

I should also add that not all APIs are even OAuth enabled! This means we need some mechanism to securely provide an MCP server an API key, for example.

[dasiths]

@wdawson thank you for that. I acknowledge that there is a long run way to get these adopted. I reckon it would be alright as long as the proposed approaches don't inhibit enterprise use cases where a RFC 8693 based option might be better suited. We may still need to explicitly call it out. i.e. Only use auth precondition based flows if the MCP server can't exchange the existing token for one scoped to the underlying resource through OBO flows etc.

[localden]

@ggoodman - check this out: https://docs.google.com/document/d/1460o7LRZPMDFxoDgdYTI4gdxjgdBMKDxnN5Ic1DGhng/edit?usp=sharing

I've been working on it as it relates specifically to primitive authorization. I am a bit uneasy with baking in a bunch of authorizationUrl logic, because that seems to be very tightly coupling tools to specific AS implementations.

I would also highly recommend cross-checking the proposal from @nbarbettini and @wdawson in #475.

[wdawson]

@ggoodman thanks for taking a look!

Re: a notification to complete the loop, we have proposed leveraging the Progress Utility for this to avoid introducing yet another mechanism. We kept that out of the initial PR to try to keep it small, but it seems like it would be very useful and could see it as a fast follow for sure. Totally agree about providing better experiences for the client when possible.

I think the insight we had with the user interaction was that fulfilling pre-conditions are necessarily going to be related to a tool call. An interaction request may be the first thing the server sends when the client connects, for example. And the interaction may not be related to auth, but instead request the user upgrade their payment plan, as an example of a sensitive transaction that should not take place via the MCP client, or simply ask the user to submit a survey in a branded fashion outside of the MCP client. These are all things I believe the recently merged elicitation was not designed for.

[ggoodman]

Re: a notification to complete the loop, we have proposed leveraging the Progress Utility for this to avoid introducing yet another mechanism. We kept that out of the initial PR to try to keep it small, but it seems like it would be very useful and could see it as a fast follow for sure. Totally agree about providing better experiences for the client when possible.

I think the insight we had with the user interaction was that fulfilling pre-conditions are necessarily going to be related to a tool call. An interaction request may be the first thing the server sends when the client connects, for example. And the interaction may not be related to auth, but instead request the user upgrade their payment plan, as an example of a sensitive transaction that should not take place via the MCP client, or simply ask the user to submit a survey in a branded fashion outside of the MCP client. These are all things I believe the recently merged elicitation was not designed for.

@wdawson fantastic! I agree with everything you said

On the note of the progress, I feel like this might be stretching its semantics a bit far. It seems quite clearly designed for communicating numerical / boolean progress. I think we'd have to be very creative to extend it to also communicate the more semantic outcomes that would befit User Interaction Requests. We'd also have to maybe rethink the id of the interaction_required response to instead be a progressToken. I am totally behind the concept but not behind that specific way of achieving it.

[wdawson]

Definitely agree. Fortunately, I think we can get there as the total is not required and we can provide a monotonically increasing number (which could even stay the same the whole time if the server wants to be less stateful) with a changing message field.

As for the progessToken, this needs to be something the MCP client generates rather than the server because it's the receiver of the progress updates. So it's decoupled from the id field of the interaction. Though when requesting progress, the MCP client will need to specify the interaction id to the server.

More to come!

[ggoodman]

Hoping to start a discussion in #475 so that we don't paint ourselves into a corner when it lands and we want to support tracking the outcome. modelcontextprotocol/modelcontextprotocol#475 (comment)

[ggoodman]

I put a little warning at the top of this proposal. Not sure how to officially 'close' it. I'll try to move my feedback over there. Let's land this!

[tadasant]

Closing per @ggoodman (let me know if this was not your intent and I'll re-open):

Not sure how to officially 'close' it. I'll try to move my feedback over there. Let's land this!

See modelcontextprotocol/modelcontextprotocol#475 (comment)