Skip to content

SEP-2385: Tool Auth Manifest#2385

Open
lececo wants to merge 6 commits intomodelcontextprotocol:mainfrom
lececo:action-level-auth-gateway
Open

SEP-2385: Tool Auth Manifest#2385
lececo wants to merge 6 commits intomodelcontextprotocol:mainfrom
lececo:action-level-auth-gateway

Conversation

@lececo
Copy link
Copy Markdown

@lececo lececo commented Mar 11, 2026

This PR proposes a new SEP that adds a Tool Authorization Manifest (TAM) to the MCP server capability model — a minimal, machine-readable declaration of authorization requirements per tool function.

Motivation and Context

The TAM addresses a gap that exists above the current authorization layer: SEP-990 and SEP-1046 establish who may connect to a server, but there is currently no protocol-level mechanism to declare what a connected agent may do. Once authenticated, a client has undifferentiated access to all tools a server exposes.

The proposal is intentionally minimal — two protocol additions only:

  1. A new capability flag authorizationManifest advertised during the initialization handshake
  2. A new server method tools/authorizationManifest that returns per-function authorization metadata (required roles, resource classification, human approval flag, audit requirement)

How Has This Been Tested?

Example repo with a minimal reference implementation:
mcp-acp-reference

Breaking Changes

No 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)
  • Documentation update

Checklist

  • 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

Enforcement architecture is explicitly out of scope for the SEP. A reference implementation demonstrating one enforcement pattern (external PDP via OPA) is provided separately.

@lececo lececo changed the title Action level auth gateway SEP 2385: Action level auth gateway Mar 11, 2026
@localden localden added auth security proposal SEP proposal without a sponsor. SEP labels Mar 11, 2026
@lececo lececo changed the title SEP 2385: Action level auth gateway SEP 2385: Tool Auth Manifest Mar 11, 2026
@lececo
Copy link
Copy Markdown
Author

lececo commented Mar 11, 2026

@localden Hello, I want to add some additional context on why this matters. When operating MCP servers in a regulated enterprise environment, every tool invocation by an AI agent is a potential compliance event. Regulators expect that access to sensitive functions is governed by documented, auditable policies.

The gap today is this: once an MCP client has a valid access token, the protocol gives it no further friction. From a compliance standpoint, that is equivalent to saying "authenticated users may do anything." That is not acceptable when the agent has access to tools that touch customer data, financial records, or regulated workflows.

Without the TAM, a Gateway operator in this context faces a specific operational problem: they have no authoritative source of truth for what a given MCP server considers sensitive. They must maintain that knowledge themselves and outside the protocol. When a server is updated by a vendor and exposes a new high-risk function, there is no signal. The Gateway does not know. The new function is reachable.

The TAM changes this by giving each server a protocol-level voice in its own access requirements. For a regulated enterprise deploying multiple MCP servers (some internal, some from external vendors) this means:

  • The server owner declares what is sensitive at the function level
  • The Gateway can consume that declaration automatically
  • Any new function with elevated requirements is visible immediately, before it can be called
  • The audit trail includes not just what was called, but what the server declared was required, which is exactly what a compliance team needs to demonstrate intent-based access control

This does not replace the Gateway or the external policy engine, but it gives them structured input that they currently lack.

@policylayer-dan
Copy link
Copy Markdown

This is a great direction. The gap between "authenticated" and "authorized to do anything" is the biggest security problem in MCP today.

A few thoughts from building enforcement tooling in this space:

1. Declaration vs. enforcement are separate concerns

The TAM as proposed is a declaration layer — the server advertises what authorization should look like. But who enforces it? If enforcement lives inside the server itself, you're trusting every server author to implement it correctly. In practice, most MCP servers are community-built and ship with no authorization logic at all.

The manifest becomes much more powerful if it's consumable by an external enforcement layer (a proxy, a gateway, or the client itself) that can make allow/deny decisions before the tool call reaches the server. This keeps the trust boundary outside the server.

2. Consider rate limiting and conditional rules

The current schema covers roles, resource classification, and human approval — but production deployments also need:

  • Rate limiting per tool (e.g., max 5 delete_repository calls per hour)
  • Conditional authorization based on arguments (e.g., create_charge allowed only if amount < 50000)
  • Time-based policies (e.g., destructive operations blocked outside business hours)

These are hard to express in a static manifest, but they're the policies that actually prevent real-world incidents.

3. The humanApproval flag is important but needs UX thought

Requiring human approval for high-risk tools is the right default. But in agentic workflows where the whole point is autonomy, blocking on human approval for every sensitive call kills the value proposition. There's a middle ground: auto-approve if the call matches a pre-approved policy, escalate if it doesn't. This keeps humans in the loop for edge cases without making the agent useless.

4. Audit requirements should include the full call context

The auditRequired flag is great, but the audit trail needs to capture more than just "tool X was called." It should include the full arguments, the policy that authorized (or denied) it, and the upstream prompt context that led to the call. Without this, the audit log is just a list of function names — not useful for incident response.

We've been working on exactly this problem at PolicyLayer — runtime enforcement of per-tool policies at the MCP transport layer. Happy to share what we've learned about policy schemas and enforcement architecture if it's useful for the SEP discussion.

@SamMorrowDrums
Copy link
Copy Markdown
Contributor

I would encourage you to check out this comment: #2382 (comment)

We are working on Annotations in an official Interest Group soon, and also there are working groups for fine grained permissions and things on the discord, and in general cold submissions for SEPs without engaging with the relevant working groups usually results in duplicative effort and SEPs never making it into the protocol.

So I'd encourage you to engage on discord!

@lececo
Copy link
Copy Markdown
Author

lececo commented Mar 12, 2026

@SamMorrowDrums Hello, thanks for the pointer. I'll check it out before going further. Happy to contribute.

@nbarbettini
Copy link
Copy Markdown
Contributor

Hi @lececo! Glad to have other people thinking about this space. I'm currently leading the fine-grained auth working group and we are thinking about similar problem statements. Please join us if you can!

Today, once a client is authenticated, it has undifferentiated access to all tools a server exposes. There is no protocol-level mechanism to declare that one function requires elevated roles, that another requires human approval, or that a resource is classified as restricted. Hosts and clients must either hardcode these requirements or leave them unenforceable.

There is an important nuance here: whether clients have undifferentiated access to all tools is a server decision. Servers are free to hide tools from the list, or reject tool calls based on their own policy. You're right that there aren't good ways to communicate that through the protocol today. That is something the working group is fixing!

This SEP adds the minimal protocol surface needed to make tool-level authorization requirements machine-readable and interoperable — without mandating a specific policy engine or enforcement architecture.

I think you are 100% correct about not mandating a specific policy engine - that is the server's decision, and the client should not need to know the server's implementation details. Hints that help agents plan can be OK.

The TAM as proposed is a declaration layer — the server advertises what authorization should look like. But who enforces it? If enforcement lives inside the server itself, you're trusting every server author to implement it correctly. In practice, most MCP servers are community-built and ship with no authorization logic at all.

@policylayer-dan Authorization is hard to get right, but I don't think that's a good reason to move authorization away from the server. It is a good reason to help server authors build authorization more easily.

The manifest becomes much more powerful if it's consumable by an external enforcement layer (a proxy, a gateway, or the client itself) that can make allow/deny decisions before the tool call reaches the server. This keeps the trust boundary outside the server.

If something else (e.g. a PDP) is enforcing an authorization decision, and the target server is not doing its own check but implicitly trusting the PDP, then I would argue that the server + PDP together is actually the server's trust boundary. This sounds like a distinction without a difference, but where it matters is whether the MCP client is responsible for reaching out to the PDP. I don't think it should be responsible for that.

@localden localden changed the title SEP 2385: Tool Auth Manifest SEP-2385: Tool Auth Manifest Mar 15, 2026
@0xbrainkid
Copy link
Copy Markdown

The TAM proposal addresses a critical gap — the authorization layer between "you can connect" and "you can do anything." Two observations from building agent identity infrastructure:

1. Authorization needs trust context, not just roles

The current TAM design uses role-based authorization (requiredRoles), which works well for known clients within an organization. But MCP is increasingly cross-organizational — an agent from Org A calling tools on Org B's server. In that case, Org B doesn't know Org A's role taxonomy.

What's needed alongside roles: trust-level-based authorization. A tool could declare:

{
  "tools/authorizationManifest": {
    "readDatabase": {
      "requiredRoles": ["data-reader"],
      "minTrustLevel": 3,
      "trustProvider": "any"
    }
  }
}

Where minTrustLevel is a standardized threshold that any trust provider (SATP, AgentScore, HOL, etc.) can satisfy. This makes TAM work across organizational boundaries without requiring shared role directories.

2. Trust scoring as a complement to human approval flags

The humanApproval flag in TAM is the right instinct — some actions need human oversight. But for high-volume agent-to-agent interactions, human approval doesn't scale.

An alternative: trust-gated escalation. Actions below a trust threshold require human approval. Above it, they're auto-approved based on the agent's verified reputation. This creates a graduated model:

  • Low trust agent → human approval required
  • Medium trust agent → some tools accessible, sensitive ones gated
  • High trust agent → full access, audit-only

This pattern is used in production by several agent identity systems (SATP uses 5 graduated trust levels with 45 attestation types; AgentScore uses a 300-850 FICO-like model).

Would be happy to help spec the trust-level extension if there's interest in making TAM interoperable with external trust providers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

auth proposal SEP proposal without a sponsor. security SEP

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

6 participants