COAZ-MCP: COAZ Binding for the Model Context Protocol - Draft 1

Table of Contents

1. Introduction

The Model Context Protocol [MCP] enables AI agents (MCP clients) to discover and invoke capabilities offered by MCP servers — tools, resources, prompts, and more — over JSON-RPC [JSONRPC]. Authorization in MCP relies on OAuth 2.1 [OAUTH21], but OAuth alone leaves some concerns unaddressed:¶

• The access token may carry scopes, but the resources a given call is actually permitted to touch depend on the user and on dynamic, fine-grained policy that scopes cannot express.¶

• If the OAuth access token is issued to the agent — which may act autonomously on behalf of a human user who is not present, or with a human in the loop — there is no standard mechanism to capture, per request, the identity of the user on whose behalf the agent acts as distinct from the agent itself.¶

The OpenID AuthZEN Authorization API [AUTHZEN] provides standardized, fine-grained authorization using the Subject-Action-Resource-Context (SARC) model. The COAZ Framework [COAZFW] defines, in a protocol-neutral way, how to project the information model of a protocol into an AuthZEN Authorization API request. This specification is COAZ-MCP, the COAZ binding for MCP: it binds that framework to MCP's information model.¶

This binding authorizes all MCP messages. It does so by defining a fixed default mapping for each MCP method (Section 7), which a PEP applies unless an MCP server has declared a more specific mapping for a particular tool (Section 8).¶

2. Relationship to the COAZ Framework

This binding fulfils the binding conformance requirements of the COAZ Framework [COAZFW] as summarized below; each row is specified in the referenced section.¶

+-------------+      +-------------+        +-------------+      +-------------+
| MCP Client  |      | MCP Gateway |        | MCP Server  |      | AuthZen PDP |
+-------------+      +-------------+        +-------------+      +-------------+
       |                    |                      |                    |
       |  1. tools/list     |    1. tools/list     |                    |
       +------------------->+--------------------->+                    |
       |                    |  tools incl. any     |                    |
       |  tools incl. any   |  x-authzen-mapping   |                    |
       |  x-authzen-mapping +<---------------------+                    |
       +<-------------------+                      |                    |
       |                    |                      |                    |
       |  2. MCP request    |   3. authorize       |                    |
       +------------------->+----------------------+------------------->|
       |                    |                      |   permit / deny    |
       |                    +<---------------------+--------------------+
       |                    |  4. forward request  |                    |
       |                    +--------------------->|  (5. server MAY    |
       |                    |                      |   re-authorize)    |
       |                    |   6. response        |                    |
       |  6. response       +<---------------------+                    |
       +<-------------------+                      |                    |
       v                    v                      v                    v

3. Information Model

This binding exposes two input variables to expressions:¶

params:

A map corresponding to the params object of the MCP JSON-RPC request being authorized. For tools/call this includes name (the tool name) and arguments (the caller-supplied values); for other methods it contains that method's parameters as defined by [MCP]. Fields are accessed using standard CEL field or index notation (e.g., params.name, params.arguments.id, params.uri, or params.arguments["customer-id"]).¶

token:

A map corresponding to the complete set of decoded claims of the JWT-formatted [RFC7519] OAuth access token used to authorize the request. All claims are available, including but not limited to sub, iss, aud, exp, and client_id. Claims are accessed using standard CEL field or index notation (e.g., token.sub, token.aud, token.client_id).¶

4. Expressions and Literals

This binding uses the framework's defaults unchanged ([COAZFW]): expressions are written in Common Expression Language [CEL], and the leading-$ discriminator with its $$ escape distinguishes them from literals. A string value beginning with $ is a CEL expression evaluated against the params and token input variables (e.g., $token.sub, $params.arguments.id, $params.arguments.amount > 10000 ? 'high' : 'standard'); any other value is a literal, used verbatim (e.g., the string customer, the number 10, the boolean true); $$50 denotes the literal string $50. Within an expression, ordinary CEL syntax applies, including CEL's own single-quoted string literals.¶

Per the COAZ expression contract ([COAZFW]), a CEL expression MUST evaluate to a single JSON value — a scalar, list, or map. A list or map returned by an expression is a single field value and does not, by itself, produce multiple evaluations. To populate an OPTIONAL field from a claim or parameter that may be absent, an expression MUST use CEL optional selection (the .? operator, e.g. $token.?client_id), which omits the field from the request when the key is missing; plain field selection on a missing key is an evaluation error.¶

An expression whose evaluation results in an error, or that yields absent or null for a REQUIRED field (subject, action, or resource), is a mapping error (Section 10.1). Every mapping in this binding — including every default mapping — contains CEL expressions, so a conforming PEP MUST include a CEL evaluator; there is no expression-free conformance level.¶

The following example illustrates how the input variables are populated. Given the 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 decoded claims:¶

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

expressions resolve as follows:¶

5. Mapping Envelopes

As defined by the COAZ Framework ([COAZFW]), a mapping is a JSON object with a single top-level member — its envelope — whose key names the AuthZEN API to call. This binding permits both envelope keys defined by the framework:¶

• evaluation — a template for a single-decision Access Evaluation request. Every default mapping in this binding uses this envelope (Section 7), and it is the RECOMMENDED envelope for declared mappings that require one decision.¶

• evaluations — a template for a multi-decision Access Evaluations request, for tools whose single invocation requires more than one decision (see Figure 7).¶

A mapping whose top-level structure is anything other than exactly one of these two keys is malformed, and the PEP MUST treat it as a mapping error (Section 10.1).¶

A PDP used with this binding MUST support the Access Evaluation API. Where a declared mapping uses the evaluations envelope, the PEP MUST either send the constructed request to the Access Evaluations API or, if its PDP does not support that API, issue one Access Evaluation request per entry — applying the top-level defaults to each entry exactly as [AUTHZEN] defines — and allow the message only if every decision is a permit.¶

6. Declaring a Mapping

An MCP server declares a mapping for a tool by including an x-authzen-mapping object within that tool's inputSchema in the tools/list response. The presence of x-authzen-mapping indicates the tool carries a declared mapping; its absence means the default mapping for tools/call applies. No separate marker field is used.¶

Because the declared mapping is carried in the tools/list response, it is available to any MCP gateway on the path — which can therefore enforce it as the PEP without out-of-band configuration (Section 2) — and to the MCP client, satisfying the framework's discoverability capability. When MCP Server Cards become available, x-authzen-mapping SHOULD also be included there.¶

The following non-normative example shows a tools/list response with one tool that declares a mapping and one that does not:¶

{
  "tools": [
    {
      "name": "get_customer",
      "description": "Get customer details",
      "inputSchema": {
        "type": "object",
        "properties": {
          "id":   { "type": "string", "description": "The customer identifier" },
          "case": { "type": "string", "description": "The case being worked on" }
        },
        "required": ["id"],
        "x-authzen-mapping": {
          "evaluation": {
            "subject": { "type": "identity", "id": "$token.sub" },
            "action": { "name": "get_customer" },
            "resource": { "type": "customer", "id": "$params.arguments.id" },
            "context": { "agent": "$token.?client_id", "case": "$params.arguments.case" }
          }
        }
      }
    },
    {
      "name": "get_local_weather",
      "description": "Get weather for the local area",
      "inputSchema": {
        "type": "object",
        "properties": { "zip": { "type": "string", "description": "Zip code" } },
        "required": ["zip"]
      }
    }
  ]
}

get_customer declares a mapping; get_local_weather does not and is therefore authorized by the default tools/call mapping (Section 7).¶

7. Default Mappings

This binding defines a default mapping for each MCP method. A PEP MUST apply the default mapping for a method unless a declared mapping applies to the specific operation (Section 8).¶

Every default mapping uses the evaluation envelope (Section 5) and shares the following subject and context, which establish the subject (the user on whose behalf the agent acts) and the agent context:¶

{
  "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action":   { "...": "per-method" },
    "resource": { "...": "per-method" }
  }
}

For methods that target the MCP server as a whole rather than a specific item, resource.id identifies this MCP server. MCP requires access tokens to be audience-bound to the target server via resource indicators [RFC8707], so the server identity is carried in the aud claim. The default mappings express this as $token.aud, with the following normative resolution: resource.id MUST be a single string identifying this server. When aud is a single string, that value is used directly. When aud is an array (as permitted by [RFC7519]), the PEP MUST select the single member that identifies this server (its own resource identifier per [RFC8707]) and use that value; resource.id MUST NOT be set to an array. If the PEP cannot resolve aud to exactly one server-identifying value, it is a mapping error (Section 10.1). A PEP that knows its own resource identifier from configuration MAY use it directly instead of deriving it from aud.¶

The default mappings are:¶

// initialize
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id", "protocol_version": "$params.protocolVersion" },
    "action": { "name": "initialize" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

// tools/list
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "tools/list" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

// tools/call  (applies when the tool declares no mapping)
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "tools/call" },
    "resource": { "type": "tool", "id": "$params.name" } } }

// resources/list
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "resources/list" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

// resources/read   (resources/subscribe and resources/unsubscribe use the
//                   same shape; only action.name differs)
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "resources/read" },
    "resource": { "type": "resource", "id": "$params.uri" } } }

// prompts/list
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "prompts/list" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

// prompts/get
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "prompts/get" },
    "resource": { "type": "prompt", "id": "$params.name" } } }

// completion/complete
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "completion/complete" },
    "resource": {
      "type": "$params.ref.type == 'ref/prompt' ? 'prompt' : 'resource'",
      "id":   "$params.ref.type == 'ref/prompt' ? $params.ref.name : $params.ref.uri" } } }

// logging/setLevel
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id", "level": "$params.level" },
    "action": { "name": "logging/setLevel" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

// tasks/get   (tasks/result and tasks/cancel use the same shape; only
//              action.name differs)
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "tasks/get" },
    "resource": { "type": "task", "id": "$params.taskId" } } }

// tasks/list
{ "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "context": { "agent": "$token.?client_id" },
    "action": { "name": "tasks/list" },
    "resource": { "type": "mcp_server", "id": "$token.aud" } } }

8. Declared Mappings

An MCP server MAY declare a mapping for a tool by including x-authzen-mapping in the tool's inputSchema (Section 6). A declared mapping has the same shape as a default mapping — an envelope naming the AuthZEN API and a template for that API's request body (Section 5) — and uses the same expression and literal rules (Section 4). A declared mapping MAY use either the evaluation or the evaluations envelope: evaluation suffices for most tools, while evaluations serves tools whose single invocation requires multiple decisions.¶

A declared mapping for a tool overrides the default tools/call mapping for that tool only. It does not affect the default mapping for any other method or for tools/call of any other tool.¶

The subject identifier (subject.id) SHOULD be anchored to the subject-identity claim of the validated access token. A declared mapping SHOULD include a subject — the request's subject under the evaluation envelope, or the top-level subject under the evaluations envelope — whose id is set to an expression resolving to the subject-identity claim (Section 3.1) — that is, $token.sub (or $token.C where an on-behalf-of claim C is designated). Where subject.id is set to the subject-identity claim, the PEP MUST verify that its resolved value equals that claim in the validated access token, treating a mismatch as a mapping error (Section 10.1); this is the trust-anchored, verification-enforced case defined by the COAZ Framework ([COAZFW]), and it prevents an MCP server — the party being authorized — from asserting the identity of a different subject.¶

Some deployments cannot convey the subject identity in a token claim — for example, an agentic deployment whose access token is issued to the agent while the identity of the acting user is carried outside the token. For these edge cases a declared mapping MAY override subject.id with a value derived from elsewhere in the operation's inputs; because full override via a CEL expression is already available, any field of the incoming request — token claim, request parameter, or otherwise — can be mapped to subject.id. An overridden subject.id SHOULD still be derived from the validated token rather than from caller-controlled request parameters. When a declared mapping sets subject.id from a source the PEP cannot verify against a token claim, the subject identity is asserted by the mapping author rather than anchored to the token; a PEP — particularly a gateway enforcing a mapping authored by an MCP server — SHOULD emit a warning in this case, and deployments SHOULD account for the additional trust this places in the mapping author (see Section 11).¶

If a declared mapping omits subject or subject.id, the PEP MUST supply the default subject identifier, $token.sub (or $token.C), so that every request still carries a token-anchored subject.¶

To close off identity smuggling, a declared mapping using the evaluations envelope MUST NOT set subject within any entry of its evaluations array; the single top-level subject applies to all evaluations. A PEP MUST reject a declared mapping that places subject inside an evaluations entry as a mapping error.¶

A declared mapping MAY otherwise shape the subject: it MAY set subject.type and additional subject attributes (under properties, per [AUTHZEN]), so that different invocations can produce different subject objects. If a declared mapping omits subject.type, the PEP MUST supply identity. Any subject attribute other than subject.id — including subject.type — is untrusted input, exactly like declared action, resource, and context attributes; only the verified subject.id is trustworthy as the authenticated identity. See Section 11.¶

For autonomous-agent use cases the context MUST include the agent identity (typically $token.?client_id).¶

{
  "subject": { "type": "identity", "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" }
}

{
  "name": "copy_object",
  "description": "Copy a storage object from one location to another",
  "inputSchema": {
    "type": "object",
    "properties": {
      "source":      { "type": "string", "description": "Source object location" },
      "destination": { "type": "string", "description": "Destination object location" }
    },
    "required": ["source", "destination"],
    "x-authzen-mapping": {
      "evaluations": {
        "subject": { "type": "identity", "id": "$token.sub" },
        "context": { "agent": "$token.?client_id" },
        "evaluations": [
          { "action": { "name": "read" },
            "resource": { "type": "storage_object", "id": "$params.arguments.source" } },
          { "action": { "name": "write" },
            "resource": { "type": "storage_object", "id": "$params.arguments.destination" } }
        ]
      }
    }
  }
}

{
  "subject": { "type": "identity", "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" } }
  ]
}

{
  "name": "transfer_funds",
  "description": "Transfer funds between accounts",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from_account": { "type": "string" },
      "to_account":   { "type": "string" },
      "amount":       { "type": "number" },
      "currency":     { "type": "string" }
    },
    "required": ["from_account", "to_account", "amount", "currency"],
    "x-authzen-mapping": {
      "evaluation": {
        "subject": {
          "type": "$token.roles.exists(r, r == 'treasury') ? 'treasury_user' : 'standard_user'",
          "id": "$token.sub"
        },
        "action": { "name": "$params.arguments.currency == 'USD' ? 'domestic_transfer' : 'international_transfer'" },
        "resource": {
          "type": "account",
          "id": "$params.arguments.from_account",
          "properties": {
            "sensitivity": "$params.arguments.amount > 10000 ? 'high' : 'standard'"
          }
        },
        "context": { "agent": "$token.?client_id", "target_account": "$params.arguments.to_account" }
      }
    }
  }
}

9. PEP Behavior

When an MCP message is processed, the PEP MUST:¶

1. Determine the JSON-RPC method. If it is a pass-through operation (Section 7), allow it without calling the PDP.¶

2. Select the applicable mapping: for a tools/call whose tool declares an x-authzen-mapping, use the declared mapping; otherwise use the default mapping for the method. A method that is neither in the pass-through set nor has a mapping MUST be denied (Section 7).¶

3. Populate params from the request's params object and token from the decoded, validated access token claims.¶

4. Resolve the mapping: literals verbatim, $-prefixed values by evaluating the CEL expression (Section 4).¶

5. Anchor the subject identity: where a mapping sets subject.id to the subject-identity claim (Section 3.1) — as every default mapping does — the effective subject.id of every decision in the constructed request — the request's subject under the evaluation envelope; the top-level subject and, after any override, the subject of each evaluations entry under the evaluations envelope — MUST equal the value of that claim in the validated access token, and the PEP MUST treat a mismatch as a mapping error (Section 10.1) and not call the PDP. Where a declared mapping instead overrides subject.id from another source (Section 8), the PEP cannot perform this verification and SHOULD emit a warning. A declared mapping MUST NOT carry a per-evaluation subject; if one is present, treat the request as a mapping error and do not call the PDP.¶

6. Construct the AuthZEN request from the resolved mapping and send it to the API named by the mapping's envelope (Section 5): the Access Evaluation API for evaluation, the Access Evaluations API for evaluations.¶

7. Enforce the response: if every decision is true (permit), allow the message to proceed; if any decision is false (deny), do not allow it and return a JSON-RPC error (Section 10.2).¶

10. Error Handling

This binding reports the COAZ denial and error categories ([COAZFW]) as JSON-RPC 2.0 [JSONRPC] error responses. In every case the PEP MUST NOT allow the message to proceed. As required by [JSONRPC], the id of each error response MUST equal the id of the request that caused it, or be null if the request id could not be determined.¶

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

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

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

11. Security Considerations

12. IANA Considerations

This specification has no IANA actions.¶

13. References

Appendix A. Relationship to Other Specifications

Appendix B. Acknowledgements

The authors would like to thank Martin Besozzi for the original proposal on AuthZEN integration for fine-grained authorization in MCP, and the members of the OpenID AuthZEN Working Group for their ongoing work on the Authorization API standard.¶

Appendix C. Notices

Copyright (c) 2025 The OpenID Foundation.¶

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶

Authors' Addresses