MCP tool annotation policies shift control from names to behavior

At a glance

What this is: This is a how-to on enforcing MCP tool annotation policies with Cedar, showing how behavioral hints like readOnly and destructive are turned into request-time authorization decisions.

Why it matters: It matters because IAM, PAM, and NHI teams need a control point that evaluates tool behavior, not just tool identity, when MCP servers expose runtime capabilities.

By the numbers:

• When AWS credentials are exposed publicly, attackers attempt access within an average of 17 minutes and as quickly as 9 minutes in some cases.

👉 Read Stacklok's how-to on enforcing MCP tool annotation policies with Cedar

Context

MCP tool annotation policies matter because naming a tool is not the same as understanding what it does. In an agentic AI environment, access decisions based only on tool names leave a gap between declared behaviour and effective authority, especially when tools can read data, modify state, or reach external systems.

Stacklok’s post focuses on closing that gap with Cedar policies that evaluate server-declared annotations at request time. The core governance issue is not whether annotations exist, but whether teams trust them enough to use them as policy inputs across NHI and emerging agentic AI workflows.

This is a practical governance problem for platform, IAM, and security teams because the control boundary moves from static allowlists to behavioural metadata. That is a better fit for MCP, but only if annotation quality, provenance, and absence handling are treated as first-class security concerns.

Key questions

Q: How should security teams govern MCP tools using behavior-based policies?

A: Start by making the tool’s declared behavior part of the authorization decision. Use annotations such as readOnlyHint and destructiveHint, require presence checks for every referenced attribute, and treat unannotated tools as denied unless a policy explicitly allows them. That gives you a scalable control model without relying on tool names alone.

Q: What breaks when MCP annotation policies do not check for missing attributes?

A: Policies become brittle because Cedar errors on absent attributes and the platform treats that as a deny. In practice, teams can end up blocking every unannotated tool or misreading a failed evaluation as a successful security control. The result is inconsistent access decisions and weak confidence in the policy boundary.

Q: How can organisations tell whether annotation-based MCP access control is working?

A: Look for three signals: permitted tools only appear when their annotations exist, destructive or external-reach tools are denied by default, and policy changes propagate consistently across all MCPServer and proxy resources. If the same tool behaves differently across workloads, the policy model is drifting from the metadata model.

Q: Who is accountable when a server misrepresents an MCP tool as read only?

A: Accountability sits with the team that owns the server, the registry, and the policy boundary, because annotation-based authorization only works when declarations are trustworthy. The control failure is not just a bad request decision, it is a governance failure in how the tool’s behavior was declared, reviewed, and validated.

Technical breakdown

How MCP annotations become policy inputs

The MCP specification lets a server declare behavioural hints such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. ToolHive caches those values from the server’s tools/list response and exposes them as boolean resource attributes for Cedar to evaluate before a call reaches the MCP server. This means the authorization layer sees the server’s declared behaviour at decision time, not the client’s claimed intent. The architecture is useful because it turns behavioral metadata into a reusable control surface across multiple MCPServer and MCPRemoteProxy workloads.

Practical implication: Treat annotation coverage as part of the authorization design, because missing or inconsistent metadata changes the decision surface.

Why Cedar’s has operator is a security requirement

A missing annotation is not equivalent to false. If a policy reads an attribute that does not exist, Cedar raises an evaluation error, and ToolHive treats that as a deny. The has operator therefore becomes the safety rail that distinguishes “explicitly false” from “not provided.” In practice, this matters because many MCP servers will not annotate every tool. Policies that skip presence checks can accidentally block all unannotated tools or create brittle rules that fail closed for the wrong reason.

Practical implication: Use presence checks in every annotation-based rule so the policy fails for the right reason, not because the attribute was absent.

Annotation-based authorization versus static allowlists

Traditional allowlists name each permitted tool or endpoint explicitly. Annotation-based authorization inverts that model by allowing whole classes of tools that satisfy behavioral criteria, such as read-only and non-destructive operations. That scales better when tool inventories change frequently, but it also shifts trust to server-declared metadata and the integrity of the registry or deployment pipeline. In other words, the policy engine can be correct while the metadata source is still wrong, which is why provenance and annotation validation matter alongside the Cedar rules themselves.

Practical implication: Pair behavioral policy with provenance checks, because safe authorization depends on trustworthy declarations, not just elegant policy syntax.

Threat narrative

Attacker objective: The attacker wants to turn declared tool metadata into unauthorized execution, using policy trust to reach tools that should have been blocked.

1. Entry occurs when a client reaches an MCP server through a permitted authorization path and requests a tool call.
2. Escalation occurs if the policy trusts an unsafe or missing annotation, or if a server falsely declares a destructive tool as read-only.
3. Impact occurs when the wrong tool is allowed to execute and the agent gains access to state-changing or externally connected actions beyond intended scope.

Breaches seen in the wild

• Meta AI Instagram Account Takeover — 20,225 Instagram accounts hijacked via compromised Meta AI support chatbot with overprivileged access.
• Replit AI Tool Database Deletion — Replit vibe coding AI assistant deletes live production database and creates 4,000 fake user records.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Behavioral policy is the right control model for MCP, but only if metadata is trusted. MCP makes tool behaviour explicit in a way static names never could, which is a real advance for NHI governance. The problem is that policy correctness and metadata truth are separate problems, and many teams will conflate them. A Cedar rule that evaluates cleanly is not evidence that the server’s declaration is accurate, so annotation governance becomes part of the access model itself.

Annotation-based access control creates a new trust boundary around tool declarations. The policy engine no longer decides only on identity and action, it decides on the declared behaviour of the tool. That means compromise can shift from credential theft to metadata deception, where a server claims safe behaviour while exposing write or network reach. Practitioners should treat annotation provenance as an authorization dependency, not as documentation.

Safe defaults matter because absent annotations are a governance condition, not a technical nuisance. The need for Cedar’s has operator shows that the absence of metadata has to be handled explicitly, or the control becomes brittle. This is the kind of operational detail that separates scalable MCP governance from policy theatre. Teams should assume incomplete annotation coverage during rollout, not after incidents force that assumption.

MCP tool governance is converging with the broader NHI lifecycle problem. Once tools are governed by declared behavior, the same questions that apply to service accounts and API keys reappear: who issued the capability, who validated it, and when should it be revoked or narrowed? The specific concept here is annotation trust debt: the gap between a tool’s declared behavior and the confidence required to use that declaration as a policy input. Practitioners should measure that gap before they expand MCP adoption.

The market is moving from name-based allowlisting to behaviour-based authorization. That change is likely to reshape how platform teams think about MCP, because it aligns better with dynamic tool ecosystems and autonomous workflows. But it also raises the bar for governance, since policy must now account for server-declared claims, provenance, and lifecycle management. Practitioners should plan for controls that verify what a tool says about itself, not only what it is called.

From our research:

• 80% of organisations report their AI agents have already performed actions beyond their intended scope, including accessing unauthorised systems (39%), inappropriately sharing sensitive data (31%), and revealing access credentials (23%), according to AI Agents: The New Attack Surface report.
• Only 52% of companies can track and audit the data their AI agents access, leaving 48% with a complete blind spot for compliance and breach investigation.
• For a control model that scales with delegated execution, see OWASP Agentic Applications Top 10 and NIST Cybersecurity Framework 2.0.

What this signals

Annotation trust debt: the operational risk is not just whether MCP tools are annotated, but whether those annotations are validated often enough to be trusted in policy. As adoption grows, security teams should expect more pressure to move from name-based allowlists to behavior-based authorization, which makes provenance and lifecycle review part of the access control story.

Because agentic systems and tool-using workloads are expanding quickly, behavioural control will become a core IAM design question rather than a niche platform concern. Teams that already manage secrets, service accounts, and workload identity should extend that governance model to MCP tool declarations before the policy surface becomes too broad to audit.

For practitioners

• Validate annotation presence before policy rollout Require Cedar rules to use has checks for every annotation referenced in a permit statement. Test unannotated tools in staging to confirm they fail closed for the intended reason, not because of evaluation errors.
• Separate tool identity from tool behaviour Build authorization rules around readOnly, destructive, idempotent, and openWorld declarations rather than tool names. Keep allowlists only for exceptional cases where behavior cannot yet be expressed reliably.
• Add provenance review to annotation governance Treat annotation values as security claims and verify them through registry controls, signing, or code-backed validation before you rely on them in production policy.
• Standardise shared policy ConfigMaps Store Cedar policy sets in reusable ConfigMaps so multiple MCPServer, MCPRemoteProxy, and gateway resources inherit the same control logic and policy updates do not drift across manifests.

Key takeaways

• MCP annotation policies shift authorization from tool names to declared tool behavior, which is a better fit for dynamic AI and NHI workflows.
• The real governance problem is trust in the annotation source, because policy correctness does not prove the metadata is accurate.
• Teams should build presence checks, provenance validation, and shared policy controls before they scale MCP tool access across environments.

Key terms

• MCP Tool Approval: A gated control pattern where a tool call is held by a gateway until a human decision permits execution. The approval is not part of the MCP standard itself; it is an implementation-layer policy that depends on client behaviour, requester identity, and release semantics.
• Annotation-Based Authorization: An access control model that permits or denies actions based on declared behaviour metadata instead of just tool names or endpoints. For MCP, it lets policy engines distinguish safe tools from risky ones, but only if the declarations are complete, trustworthy, and evaluated with presence checks.
• Cedar Policy Evaluation: The decision process Cedar uses to determine whether a request should be allowed or denied. It evaluates policy statements against principals, actions, and resources, and in this context it can use MCP tool annotations as resource attributes when those attributes exist.
• Annotation Trust Debt: The gap between a tool’s declared behaviour and the level of confidence required to use that declaration as a security control. It grows when servers can self-describe unsafe behaviour as safe, when provenance is weak, or when policy assumes annotation truth without validation.

What's in the full article

Stacklok's full how-to covers the operational detail this post intentionally leaves for the source:

• Step-by-step Cedar policy examples for MCPServer, MCPRemoteProxy, and VirtualMCPServer manifests
• Complete ConfigMap and inline authorization patterns for reusable Kubernetes deployments
• Ready-to-use policy profiles for observe-only, safe-tools, and RBAC-plus-annotations postures
• The registry and provenance discussion behind trusting annotation values in production

👉 Stacklok's full post includes the Kubernetes manifests, policy profiles, and annotation trust discussion in implementation detail.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity security are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are responsible for identity security strategy or IAM programme maturity, it is worth exploring.