ext-auth

Minor editorial changes (actual requests look like these). The Pragma cache directive is no longer in use. Motivation and Context How Has This Been Tested? Breaking Changes Types of changes [ ] Bug fix (non-breaking change which fixes an issue) [ ] New feature (non-breaking change which adds functionality) [ ] Breaking change (fix or feature that would cause existing functionality to change) [x] Documentation update Checklist [x] I have read the MCP Documentation [ ] My code follows the repository's style guidelines [ ] New and existing tests pass locally [ ] I have added appropriate error handling [ ] I have added or updated documentation as needed Additional context

Is your feature request related to a problem? Please describe. The current Authorization Spec draft focuses many details on a client that performs the login itself with Authorization Code Flow + PKCE. I see use cases where the client would not interact with the user, and instead the host application receives an access token from some other application that has been granted access to the host app on behalf of a user. When this happens, it seems Token Exchange is the proper method to obtain a new access token meant for the MCP Server. I wonder if there needs to be some way for a client to know the expected value of the MCP Server's audience claim. I'd like to open discussion surrounding this use case. Describe the solution you'd like I wonder if there could be a section in the Authorization spec dedicated to this use case. Evidently the token validation in this case would need to be performed by the Host application instead of the MCP Client (which I'm not sure is in the scope of this spec?). However, the token exchange is something that I believe should fall to the MCP Client if in other cases the MCP Client is responsible for handling the login. Given this affects the implementation of an MCP Client, I believe this belongs in the main authorization spec. Describe alternatives you've considered If this is perhaps not meant for the main authorization spec, I feel this is a common enough pattern at least worth a mention in the security-best-practices doc. Additional context This issue is semi-related to modelcontextprotocol/modelcontextprotocol#214 but is a slightly different (maybe broader) use case. Also having been watching the open PR modelcontextprotocol/modelcontextprotocol#408 possibly there should be some discussion of token exchange by the server to downstream tool, but perhaps that use case discussion can belong in another issue.

Author: @tulshi Status: Draft Type: Feature Proposal Created: 2026-02-06 Abstract COAZ (pronounced “cozy”) stands for “Compatible with OpenID AuthZen”. This SEP introduces , an extension to the MCP definition's . It provides a standardized way to map tool arguments and session tokens to the OpenID AuthZEN Subject-Action-Resource-Context (SARC) model. This enables MCP clients and proxies to perform fine-grained, parameter-level authorization checks before executing tools. Motivation MCP servers offer tools to MCP clients (aka agents). Tools are described in the response to the call of the MCP server. For each tool listed, the MCP server includes an field. The value of this field is a JSON schema object that describes the input required by this tool. The MCP client then calls the tool and provides parameters in accordance with the input schema. Authorization in MCP relies on OAuth 2.1. However, there are a couple of concerns that are left unaddressed by it: The OAuth token is issued to the agent, which may be acting either autonomously on behalf of a human user who might not be present, or with a “human user in the loop”. If the token is issued with the agent identity as the principal, then one needs to figure out how to capture the user identity on whose behalf the tool is being invoked. The OAuth token may have specific scopes that limit what the user or the agent can do. However, depending on the user on whose behalf the agent is acting, and what that user is currently authorized to access, the actual set of resources that may be permitted in a specific call may be limited. There is no way to capture that using just scopes. Implementing dynamic, fine-grained authorization In order to achieve dynamic, fine-grained authorization in MCP, we need the following in addition to the OAuth capabilities already present, we need to be able to: Verify the agent as well as the user on whose behalf the agent is acting, for each MCP server tool call the agent makes. Determine the specific resources each tool call results in. Determine the context of each tool call. The AuthZen API is able to provide dynamic, fine-grained authorization, but the API requires specific parameters. The purpose of this proposal is therefore to: Declare whether a tool is AuthZen compatible or not, and If a tool is AuthZen compatible, how does it map its input to the parameters required by AuthZen. Architecture Once a tool is declared as being AuthZen compatible, when the tool is called, an intermediate MCP gateway, or the MCP server itself calls the AuthZen PDP. The caller uses the specified mapping to determine the AuthZen API parameter values from the tool call. It is also possible for the MCP client to call the AuthZEN PDP before making the tool call, but since the MCP Client may not be trusted by the MCP server, doing so may not prevent the MCP server from calling the PDP again. Relationship to Existing Proposals This SEP acknowledges and complements ext-auth Issue \#14: OpenID AuthZEN Integration for Fine-Grained Authorization. Issue \#14 establishes the mechanism for how an AuthZen PDP may be called within an MCP client and server interaction. This SEP offers a way to map the parameters of the MCP tool invocation to the parameters required by the AuthZen API. Proposal Declaring support for AuthZen MCP servers may advertise certain tools they support as being AuthZen compatible by including a field named (i.e., Compatible with OpenID AuthZen) in the object representing a tool in the response to . When Server Cards become available in MCP, this field may be included in the tool object in the server card. The value of this field MUST be set to to indicate support for AuthZen. For example: In the above example, the tool is AuthZen compatible (because it has the field set to ), but the tool is not AuthZen compatible, because it does not include a field. COAZ tool input schema The AuthZen API expects the following parameters in each call: Subject: Required. Is the user for whom the access is requested. If an AI agent is operating autonomously, then this need not be the identity to whom the access token is issued. It might be captured in a parameter that describes the user on whose behalf the agent is acting. Action: Required. This is the tool name, or some 1:1 mapping of the tool name that is meaningful to the PDP. Resource: Required. This is the resource that is being requested to be accessed as a part of invoking this tool. Note that this Resource is not the same as a Resource declared by the MCP server. Context: Optional. Any additional data that can help the PDP make an access decision. For autonomous use-cases, the context MUST be present and it MUST include the identity of the agent. So to map elements from a JWT formatted authorization token, or the tool description, the following is proposed for tools. In this proposal, the values of the fields can contain the following variables: : Refers to the field of the of the object. : Refers to the JWT formatted OAuth token used to authorize the tool call Fields within these variables MUST be referred to using JSONPath. The following field is proposed to be added to the object for tools: An object MUST be included in the object. Its value is a JSON object that has the following fields: : Required. Describes the parameter of the AuthZen API : Required. Describes the parameter of the AuthZen API : Required. Describes the parameter of the AuthZen API : Optional. Describes the parameter of the AuthZen API. If this is missing then the PEP MUST construct a JSON object containing a single field named , whose value is the tool name. Note that at least one field of the or parameters MUST be derived from the variable. Schema The schema of the object is as follows: Example The following is an example of a tool description of a coaz tool: In the above example, the does not specify an action, which means that the action name in the AuthZen API call will be the tool name. Error handling The AuthZen PDP may respond with a “deny” result to a request. In that case, the PEP (the MCP gateway or the MCP server) MUST respond with an appropriate error status and message to the MCP client. This SEP proposes to use the error code number \-32401 as the error status code for JSON-RPC. The status message in the response MAY be copied from the OpenID AuthZen field in the error response. So an example error response is as follows: Rationale The primary wins from this SEP are: 1. Externalization: Decouples security logic from business logic. 2. Zero-Trust for Agents: Distinguishes between the human (Subject) and the AI agent (Context). 3. AuthZEN Alignment: Leverages a ratified OpenID standard rather than creating a proprietary MCP-specific authorization language. Addressing Protocol Bloat A common concern for MCP extensions is the introduction of "vendor-specific" or "over-engineered" schemas. This proposal mitigates bloat in three ways: Opt-in Complexity: The field is entirely optional. Minimalist servers that do not require fine-grained authorization (FGA) are not forced to implement or even understand the schema. Leveraging Standards: Rather than inventing an MCP-specific authorization DSL, we utilize OpenID AuthZEN 1.0. This allows the protocol to remain "security-neutral" by deferring the heavy lifting to external, purpose-built policy engines. Standardized Semantic Mapping:** Currently, developers are already embedding security logic in their tool handlers. By formalizing this mapping, we replace fragmented, non-standard code with a declarative schema that is machine-readable by gateways and proxies. Acknowledgements Thanks to Martin Besozzi for their SEP: “OpenID AuthZEN Integration for Fine-Grained Authorization” (Issue \#14), which started my thought process in this direction.