AuthZen Profile for Model Context Protocol Tool Authorization - Draft 1

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

This specification uses the following terms:¶

MCP:

The Model Context Protocol, which enables AI agents to integrate with independent services.¶

MCP Client:

An AI agent or application that connects to MCP servers and invokes tools. The MCP Client acts as the caller in MCP.¶

MCP Server:

A service that exposes tools, resources, and prompts to MCP clients via the Model Context Protocol.¶

MCP Gateway:

An intermediary that sits between an MCP client and one or more MCP servers. A gateway MAY perform authorization checks on behalf of the MCP server.¶

Tool:

A callable function exposed by an MCP server, described by a name, description, and input schema.¶

PDP:

Policy Decision Point, as defined in [AUTHZEN]. A service that evaluates authorization requests and returns access decisions.¶

PEP:

Policy Enforcement Point, as defined in [AUTHZEN]. In the context of this specification, the PEP is typically the MCP gateway or MCP server that calls the AuthZen PDP and enforces the resulting decision.¶

COAZ:

Compatible with OpenID AuthZen (pronounced "cozy"). A marker indicating that an MCP tool supports the AuthZen mapping defined in this specification.¶

2.1. Architecture

The response to the tools/list call of MCP has the inputSchema in it. The inputSchema declares whether the tool is COAZ or not.¶

If a tool is COAZ, then the inputSchema includes a mapping of how the tool parameters are mapped to the AuthZen PDP.¶

By including it in the response of the tools/list call, the COAZ mapping is made available to the MCP Client. This is so that the LLM (or the MCP Client) can determine the values for the tool parameters appropriately when calling the tool.¶

The authorization flow proceeds as follows: When the tool is called, a PEP (either an MCP gateway or the MCP server itself) calls the AuthZen PDP. The PEP uses the mapping defined in this specification to construct the AuthZen request parameters from the tool call arguments and the associated access token.¶

It is also possible for the MCP client to call the AuthZen PDP before making the tool call. However, since the MCP client may not be trusted by the MCP server, this does not preclude the MCP server from performing its own authorization check.¶

The architecture is described below:¶

+-------------+        +-------------+           +-------------+       +-------------+
|             |        |             |           |             |       |             |
| MCP Client  |        | MCP Gateway |           | MCP Server  |       | AuthZen PDP |
|             |        |             |           |             |       |             |
+-------------+        +-------------+           +-------------+       +-------------+
       |                      |                         |                     |
       |     1. List Tools    |                         |                     |
       |                      |                         |                     |
       +--------------------->|      1. List Tools      |                     |
       |                      |                         |                     |
       |                      |------------------------>|                     |
       |                      |                         |                     |
       |                      |                         |                     |
       |                      |                         |                     |
       |                      |<------------------------+                     |
       |                      |   Tools list including  |                     |
       |<---------------------+       COAZ mapping      |                     |
       | Tools list including |                         |                     |
       |     COAZ mapping     |                         |                     |
       |                      |                         |                     |
       |                      |                         |                     |
       |     2. Tool call     |                         |                     |
       |                      |                         |      3. Verify      |
       +--------------------->|                         |     permissions     |
       |                      |                         |                     |
       |                      +-------------------------+-------------------->|
       |                      |                         |                     |
       |                      |                         |                     |
       |                      <-------------------------+---------------------+
       |                      |                         |    Permit tool      |
       |                      |                         |                     |
       |                      |                         |                     |
       |                      |       4. Tool call      |                     |
       |                      |                         |                     |
       |                      |------------------------>|                     |
       |                      |                         |      5. Verify      |
       |                      |                         |     permissions     |
       |                      |                         |                     |
       |                      |                         +-------------------->|
       |                      |                         |                     |
       |                      |                         |                     |
       |                      |                         |<--------------------+
       |                      |<------------------------+    Permit tool      |
       |                      |                         |                     |
       |<---------------------+    6. Tool response     |                     |
       |                      |                         |                     |
       |   6. Tool response   |                         |                     |
       |                      |                         |                     |
       v                      v                         v                     v
+-------------+        +-------------+           +-------------+       +-------------+
|             |        |             |           |             |       |             |
| MCP Client  |        | MCP Gateway |           | MCP Server  |       | AuthZen PDP |
|             |        |             |           |             |       |             |
+-------------+        +-------------+           +-------------+       +-------------+

In the above diagram, the arrows 3 and 5 are alternatives to each other. If a Gateway exists, then it calls the AuthZen PDP, but if it doesn't exist, then the Server calls the AuthZen PDP. It is possible, but redundant for both these components to call the AuthZen PDP.¶

4.1. Overview

For COAZ tools, the inputSchema object MUST include an x-coaz-mapping field. This field contains a JSON object whose fields are arrays that define how the tool's input parameters and the caller's access token map to the AuthZen information model entities: Subject, Action, Resource, and Context.¶

4.2. Mapping Expressions

Values within the x-coaz-mapping object MAY be dynamically derived from elements of the tool invocation using Common Expression Language (CEL) [CEL] expressions.¶

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_customer",
    "arguments": {
      "id": "cust-12345",
      "case": "case-67890"
    }
  }
}

{
  "sub": "alice@example.com",
  "client_id": "http://agentprovider.com/agent-app-id",
  "iss": "https://auth.example.com",
  "exp": 1750000000
}

4.3. Mapping Object Schema

The x-coaz-mapping object MUST contain the following fields:¶

subject:

REQUIRED. An array of JSON objects describing how to construct the subject parameter of the AuthZen Access Evaluation API request. At least one field of the subject MUST be derived from the token input variable via a CEL expression.¶

action:

OPTIONAL. An array of JSON objects describing how to construct the action parameter of the AuthZen Access Evaluation API request. If this field is absent, the PEP MUST use a single-element array containing {"name": "<tool name>"}, where <tool name> is the name of the MCP tool.¶

resource:

REQUIRED. An array of JSON objects describing how to construct the resource parameter of the AuthZen Access Evaluation API request. The object MAY contain CEL string literals for static values and/or CEL expressions referencing tool call parameters and token claims.¶

context:

REQUIRED. An array of JSON objects describing how to construct the context parameter of the AuthZen Access Evaluation API request. For autonomous agent use cases, the context MUST include the identity of the agent. At least one field of either the subject or the context MUST be derived from the token input variable via a CEL expression.¶

At least one field across the subject and context parameters MUST be derived from the token input variable.¶

4.4. Processing Rules

The following rules MUST be used to construct the Authorization API request from the above mapping object:¶

• If all fields specified in a mapping have arrays with a single element in them, then the evaluation API is called.¶

• If any field has an array with more than one element, then the evaluations API is called.¶

• If the PDP does not support the evaluations API and there is at least one field with more than one element in the COAZ mapping, then the PEP MUST give an error when it discovers the tool descriptions. This can be at initialization or in response to the tools/list call, depending on when it can access the description.¶

• All fields with single element arrays are specified outside of the evaluations array in the evaluations API request.¶

• If the action field is missing, it is assumed to be a single-element array containing {"name": "<tool name>"}, where <tool name> is the MCP tool name.¶

• All fields that have more than one element in the array values MUST have the same number of elements. A PEP MUST give an error if this is not the case.¶

• All fields with more than one element are specified inside the evaluations array in the evaluations API request. Each successive element of the evaluations array contains the successive value from each multi-valued field.¶

4.5. Schema

The schema of the x-coaz-mapping object is as follows:¶

{
  "type": "object",
  "required": ["subject", "resource", "context"],
  "properties": {
    "subject": {
      "type": "array",
      "description": "Array of subjects requesting access, as defined in {{AUTHZEN}}",
      "items": {
        "type": "object",
        "description": "Subject object as specified in Section 3.2 of {{AUTHZEN}}"
      }
    },
    "action": {
      "type": "array",
      "description": "Array of actions to be performed on the resources (optional)",
      "items": {
        "type": "object",
        "description": "Action object as specified in Section 3.3 of {{AUTHZEN}}"
      }
    },
    "resource": {
      "type": "array",
      "description": "Array of resources to be accessed, as defined in {{AUTHZEN}}",
      "items": {
        "type": "object",
        "description": "Resource object as specified in Section 3.1 of {{AUTHZEN}}"
      }
    },
    "context": {
      "type": "array",
      "description": "Array of contextual information relevant to the authorization decision",
      "items": {
        "type": "object",
        "description": "Context object as specified in Section 3.4 of {{AUTHZEN}}"
      }
    }
  }
}

4.6. Single-valued Example

The following is a non-normative example of a complete tool definition with a COAZ mapping. The example uses the same tools/call request and access token from Section 4.2.3:¶

Given the following tools/call request:¶

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_customer",
    "arguments": {
      "id": "cust-12345",
      "case": "case-67890"
    }
  }
}

And an access token with the following decoded claims:¶

{
  "sub": "alice@example.com",
  "client_id": "http://agentprovider.com/agent-app-id",
  "iss": "https://auth.example.com",
  "exp": 1750000000
}

The tool definition is as follows:¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_customer",
        "coaz": true,
        "description": "Get customer details",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The customer identifier"
            },
            "case": {
              "type": "string",
              "description": "The case being worked on by the agent"
            }
          },
          "x-coaz-mapping": {
            "resource": [{
              "id": "params.arguments.id",
              "type": "'customer'"
            }],
            "subject": [{
              "type": "'user'",
              "id": "token.sub"
            }],
            "context": [{
              "agent": "token.client_id",
              "case": "params.arguments.case"
            }]
          }
        }
      }
    ]
  }
}

In this example:¶

• The resource is constructed with the type set to the CEL string literal 'customer' and the id derived from the tool call's id argument using the CEL expression params.arguments.id.¶

• The subject is constructed with the type set to the CEL string literal 'user' and the id derived from the sub claim of the access token using token.sub.¶

• The context includes the client_id claim from the access token (token.client_id) as the agent identifier, and the case argument (params.arguments.case) from the tool invocation.¶

• The action is not specified in the mapping, so the PEP constructs it as {"name": "get_customer"} using the tool name.¶

The resulting AuthZen Access Evaluation API request would be:¶

{
  "subject": {
    "type": "user",
    "id": "alice@example.com"
  },
  "action": {
    "name": "get_customer"
  },
  "resource": {
    "type": "customer",
    "id": "cust-12345"
  },
  "context": {
    "agent": "http://agentprovider.com/agent-app-id",
    "case": "case-67890"
  }
}

4.7. Multi-valued Example

The following is a non-normative example of a tool that copies an object from one storage location to another. The operation requires two distinct privileges: read access on the source location and write access on the destination location. These are expressed as two entries in the action and resource arrays of the x-coaz-mapping object. The subject and context are the same for both checks and are therefore each a single-element array.¶

Given the following tools/call request:¶

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "copy_object",
    "arguments": {
      "source": "/bucket/reports/q1.pdf",
      "destination": "/bucket/archive/q1.pdf"
    }
  }
}

And an access token with the following decoded claims:¶

{
  "sub": "alice@example.com",
  "client_id": "http://agentprovider.com/agent-app-id",
  "iss": "https://auth.example.com",
  "exp": 1750000000
}

The tool definition is as follows:¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "copy_object",
        "coaz": true,
        "description": "Copy a storage object from one location to another",
        "inputSchema": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "description": "The source object location"
            },
            "destination": {
              "type": "string",
              "description": "The destination object location"
            }
          },
          "x-coaz-mapping": {
            "action": [
              { "name": "'read'" },
              { "name": "'write'" }
            ],
            "resource": [
              { "type": "'storage_object'", "id": "params.arguments.source" },
              { "type": "'storage_object'", "id": "params.arguments.destination" }
            ],
            "subject": [{
              "type": "'user'",
              "id": "token.sub"
            }],
            "context": [{
              "agent": "token.client_id"
            }]
          }
        }
      }
    ]
  }
}

In this example:¶

• The action array has two elements: read for the source and write for the destination.¶

• The resource array has two elements: the source location and the destination location, each taken from the corresponding tool input property.¶

• The subject and context arrays each have a single element, as the same caller identity and agent context apply to both privilege checks.¶

Because action and resource each contain more than one element, the Processing Rules require the PEP to call the AuthZen Access Evaluations API. The single-element subject and context values are placed at the top level of the request as defaults. The resulting AuthZen Access Evaluations API request would be:¶

{
  "subject": {
    "type": "user",
    "id": "alice@example.com"
  },
  "context": {
    "agent": "http://agentprovider.com/agent-app-id"
  },
  "evaluations": [
    {
      "action": { "name": "read" },
      "resource": { "type": "storage_object", "id": "/bucket/reports/q1.pdf" }
    },
    {
      "action": { "name": "write" },
      "resource": { "type": "storage_object", "id": "/bucket/archive/q1.pdf" }
    }
  ]
}

4.8. CEL Conditions Example (Non-normative)

The following non-normative example demonstrates the use of CEL conditional expressions and built-in functions within a COAZ mapping. A transfer_funds tool uses CEL ternary expressions to dynamically derive mapping values based on the tool call arguments and token claims:¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "transfer_funds",
        "coaz": true,
        "description": "Transfer funds between accounts",
        "inputSchema": {
          "type": "object",
          "properties": {
            "from_account": {
              "type": "string",
              "description": "Source account identifier"
            },
            "to_account": {
              "type": "string",
              "description": "Destination account identifier"
            },
            "amount": {
              "type": "number",
              "description": "Transfer amount"
            },
            "currency": {
              "type": "string",
              "description": "Currency code (e.g., USD, EUR)"
            }
          },
          "x-coaz-mapping": {
            "resource": [{
              "type": "'account'",
              "id": "params.arguments.from_account",
              "sensitivity": "params.arguments.amount > 10000 ? 'high' : 'standard'"
            }],
            "action": [{
              "name": "params.arguments.currency == 'USD' ? 'domestic_transfer' : 'international_transfer'"
            }],
            "subject": [{
              "type": "token.roles.exists(r, r == 'treasury') ? 'treasury_user' : 'standard_user'",
              "id": "token.sub"
            }],
            "context": [{
              "agent": "token.client_id",
              "target_account": "params.arguments.to_account"
            }]
          }
        }
      }
    ]
  }
}

In this example:¶

• The resource.sensitivity field uses a ternary expression to set the value to "high" when the transfer amount exceeds 10000, or "standard" otherwise.¶

• The action.name field uses a string equality check to distinguish between domestic and international transfers based on the currency.¶

• The subject.type field uses the CEL exists() macro to check whether the token's roles claim contains "treasury", setting the subject type accordingly.¶

5.1. Constructing the AuthZen Request

When a COAZ tool is invoked, the PEP MUST:¶

1. Parse the x-coaz-mapping from the tool's inputSchema.¶

2. Evaluate all CEL expressions with the params variable populated from the tools/call JSON-RPC request and the token variable populated from the decoded access token claims.¶

3. Construct the AuthZen Access Evaluation or Evaluations API request according to the processing rules described in Section 4.4 using the resolved values.¶

4. Send the request to the configured AuthZen PDP.¶

5.2. Handling the AuthZen Response

6.1. COAZ Mapping Errors

A COAZ mapping error occurs when the PEP cannot construct a valid AuthZen request from the x-coaz-mapping and the tools/call [MCP] request. This includes, but is not limited to:¶

• A CEL expression references a field that does not exist in the params or token input variables.¶

• A CEL expression fails to evaluate (e.g., type error, division by zero).¶

• The x-coaz-mapping object is malformed or missing required fields.¶

• Multi-valued arrays have mismatched element counts (see Section 4.4).¶

When a mapping error occurs, the PEP MUST NOT execute the tool and MUST return a JSON-RPC error response using the standard Invalid Params error code:¶

Error Code:

-32602¶

Meaning:

Invalid params. The PEP was unable to construct a valid AuthZen request from the COAZ mapping and the tool call parameters.¶

The message field SHOULD describe the specific mapping failure to aid debugging.¶

The following is a non-normative example of a mapping error response:¶

{
  "jsonrpc": "2.0",
  "id": 456,
  "error": {
    "code": -32602,
    "message": "COAZ mapping error: CEL expression 'params.arguments.region' failed: no such key 'region' in params.arguments"
  }
}

6.2. Authorization Denial

When the PEP receives a deny decision from the AuthZen PDP, it MUST respond to the MCP client with a JSON-RPC error response.¶

This specification defines the following error code for authorization failures:¶

Error Code:

-32401¶

Meaning:

Unauthorized. The authorization check performed by the AuthZen PDP resulted in a deny decision for the requested tool invocation.¶

The message field of the JSON-RPC error object MAY be populated from the context.reason field of [AUTHZEN] Access Evaluation API response, if present.¶

The following is a non-normative example of an authorization denial response:¶

{
  "jsonrpc": "2.0",
  "id": 789,
  "error": {
    "code": -32401,
    "message": "Access denied: insufficient permissions for customer record"
  }
}

6.3. PDP Communication Errors

If the PEP is unable to reach the AuthZen PDP or receives an invalid response, the PEP MUST NOT execute the tool and MUST return a JSON-RPC error response using the standard Internal Error code:¶

Error Code:

-32603¶

Meaning:

Internal error. The PEP was unable to complete the authorization check due to a communication failure with the AuthZen PDP.¶

The following is a non-normative example of a PDP communication error response:¶

{
  "jsonrpc": "2.0",
  "id": 101,
  "error": {
    "code": -32603,
    "message": "Authorization service unavailable"
  }
}

7.1. Externalized Authorization

This profile promotes the externalization of authorization logic from MCP tool implementations. By delegating authorization decisions to an AuthZen PDP, tool developers can separate security logic from business logic, enabling centralized policy management and consistent enforcement across tools.¶

7.2. Zero-Trust for AI Agents

A critical security consideration for MCP deployments is the distinction between the human user (represented as the AuthZen Subject) and the AI agent (represented in the AuthZen Context). This separation enables policies that can independently evaluate the trust level of both the user and the agent, supporting zero-trust architectures for AI agent interactions.¶

7.3. Token Integrity

The access token referenced by the token CEL input variable MUST be validated by the PEP before extracting claims for the AuthZen request. The PEP MUST verify the token signature, issuer, audience, and expiration in accordance with [RFC7519] and the OAuth framework in use.¶

7.4. Transport Security

All communication between the PEP and the AuthZen PDP MUST use TLS as specified in the transport requirements of [AUTHZEN].¶

7.5. Mapping Integrity

The x-coaz-mapping is provided by the MCP server as part of the tool definition. MCP clients and gateways that act as PEPs SHOULD validate that the mapping is well-formed and that all referenced properties exist in the tool's inputSchema before constructing the AuthZen request.¶

7.6. Deployment Coverage

Implementors SHOULD ensure that at least one COAZ-aware PEP in the deployment path evaluates the x-coaz-mapping for each tool invocation. If no PEP in the request path processes the mapping, no AuthZen authorization occurs and access control falls back to whatever other mechanisms are in place (e.g., OAuth scopes). Deployment architectures SHOULD be validated to confirm that COAZ mappings are consumed by an appropriate enforcement point.¶

9.1. Normative References

[AUTHZEN]

Gazitt, O., Brossard, D., and A. Tulshibagwale, "Authorization API 1.0", 2026, <https://openid.net/specs/authorization-api-1_0.html>.

[CEL]

Google, "Common Expression Language", 2024, <https://cel.dev/>.

[JSONRPC]

"JSON-RPC 2.0 Specification", 2013, <https://www.jsonrpc.org/specification>.

[MCP]

Anthropic, "Model Context Protocol Specification", 2025, <https://spec.modelcontextprotocol.io/>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

9.2. Informative References

[OAUTH21]

"The OAuth 2.1 Authorization Framework", 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC9396]

Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, <https://www.rfc-editor.org/rfc/rfc9396>.

A.1. OpenID AuthZen Authorization API

This specification is a profile of the OpenID AuthZen Authorization API [AUTHZEN]. It defines a specific usage pattern for the Access Evaluation API endpoint in the context of MCP tool invocations, including how to construct the Subject, Action, Resource, and Context parameters from MCP tool definitions and OAuth access tokens.¶

A.2. Model Context Protocol

This specification extends the MCP [MCP] tool definition schema by introducing the coaz field and the x-coaz-mapping extension to the inputSchema object. These extensions are designed to be backward compatible with existing MCP implementations; servers and clients that do not understand COAZ will simply ignore these fields.¶

A.3. OAuth 2.1

This specification complements the OAuth 2.1 [OAUTH21] authorization framework used by MCP. While OAuth provides authentication and coarse-grained authorization via scopes, this profile enables fine-grained, parameter-level authorization decisions that consider the specific resources and context of each tool invocation.¶

B.1. Opt-in Complexity

The COAZ mapping is entirely optional. MCP servers that do not require fine-grained authorization are not required to implement or understand the x-coaz-mapping schema. This ensures that the profile does not impose unnecessary complexity on simple deployments.¶

B.2. Leveraging Standards

Rather than defining an MCP-specific authorization language, this profile leverages the OpenID AuthZen Authorization API [AUTHZEN], a ratified standard designed for interoperable authorization. This allows the MCP ecosystem to remain authorization-implementation neutral by deferring policy evaluation to external, purpose-built policy engines.¶

B.3. Declarative Mapping

The x-coaz-mapping replaces ad-hoc, implementation-specific authorization code that developers would otherwise embed in tool handlers. By formalizing the mapping as a declarative schema, authorization intent becomes machine-readable and can be processed by gateways and proxies without requiring knowledge of the tool's internal implementation.¶