Skip to main content

Definition Pinning

An MCP tool can change after you approved it: its description, its input schema or the server that provides it. Definition pinning lets you record the definition you approved for an mcp_tool asset and notice when a call arrives for a different one. In strict mode such a call is denied with the reason definition_changed.

Pinning is opt-in per asset. An asset with no pin behaves exactly as before.

How it works​

  1. A super_admin pins the digest of the approved definition on the asset.
  2. The enforcement point sends the digest of the definition it observed with each call.
  3. The control plane compares the two.

If there is no pin, or the digests are equal, the call continues as usual. If the digests differ, a strict mode denies the call, and permissive and observe let it continue and record an asset.definition.changed event. The mode is the one that applies to the asset: the organization mode, or an override for its environment, asset type or risk tier.

The check runs after the kill switch and before approvals and policy evaluation. So a definition_changed deny does not depend on your policies, an approved but unredeemed approval is not redeemed while the definition differs (it stays approved and can be used after the definition matches again), and break-glass never covers it.

Where it works​

Entry pointSupported
MCP adapter for local stdio serversYes. The adapter reads the server's tool list and sends the digest itself.
SDKsYes, if your code supplies the digest. The SDKs do not compute it.
MCP over HTTP through the Envoy adapterNo. Envoy cannot read the server's tool list, so it sends no digest and the pin has no effect.

The MCP adapter learns a tool's definition from the tools/list result your MCP client requests. It never requests the list itself during a call. It sends the digest only when it has a current list that contains the called tool, and it sends nothing, without an error, when it does not. A server that changes a tool without telling the client keeps the earlier digest until the client lists tools again or the server sends a list-changed notification.

What pinning does not protect against​

The digest comes from the caller. Anyone who can call the decision API with a decision:run key can send any digest, including the approved one. Pinning therefore notices a changed definition that an honest enforcement point sees, such as a tool that was altered after you approved it. It is not a defense against a malicious caller, and it is not a substitute for policies.

The digest​

The digest is sha256: followed by 64 lowercase hexadecimal characters, with the canon value mcp-tool-definition:v1. It is the SHA-256 of the text openprodkt:mcp-tool-definition:v1: followed by the canonical JSON (RFC 8785) of an object with these members:

MemberRule
nameRequired. The tool name.
descriptionIncluded when the tool has one, omitted otherwise.
inputSchemaRequired. The tool's input schema.
server_versionIncluded when the server reports a version, omitted otherwise.

Text is hashed as UTF-8 with no Unicode normalization. Numbers in the schema must be integers within the safe integer range; a definition with any other number cannot be hashed, and the adapter then sends no digest. Only the digest, the canon value and the server version leave the adapter. The description and schema are never sent to the control plane.

Pinning a tool​

Pins are managed through the API; the Console does not manage them.

ActionEndpointWho
Read a pinGET /v1/assets/{id}/definition-pinAn API key with assets:read, or any signed-in role except the auditor. A user sees pins only for assets they own.
Set or change a pinPUT /v1/assets/{id}/definition-pinA signed-in super_admin only. API keys never can.
Remove a pinDELETE /v1/assets/{id}/definition-pinA signed-in super_admin only. API keys never can.

PUT takes {"digest": "sha256:...", "canon": "mcp-tool-definition:v1"} and returns definition-pin.v1 with asset_id, digest, canon, set_by and set_at. Setting the digest a pin already has changes nothing and records nothing. Writes also need the asset-management entitlement that asset updates need. Every response is Cache-Control: no-store.

  • Pins are explicit. A pin is only ever set by a super_admin. A digest that a call carries never creates or changes a pin, and the first digest seen is not trusted automatically.
  • mcp_tool assets only. Any other asset type returns 400 with asset_type_not_supported.
  • Errors. 400 with invalid_digest or invalid_canon; 404 for an unknown asset, another organization's asset, an asset a user does not own, or an asset with no pin.

What the caller sees​

A denied call has the same shape as a policy deny: HTTP 403, decision deny, reason definition_changed, with no policy ID and no approval fields. It carries a decision ID. The SDKs, the MCP adapter and the Envoy adapter treat it as an ordinary deny and never call the tool. The Envoy adapter for plain HTTP and gRPC includes the reason in its deny body (exact match only).

A definition_changed deny is recorded as a decision and counts toward your decision quota like any recorded deny. It records no operation allow and creates no approval.

The observation field​

POST /v1/evaluate and POST /v1/proxy/evaluate accept an optional definition_observation:

{
"definition_observation": {
"digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"canon": "mcp-tool-definition:v1",
"server_version": "1.4.2"
}
}

server_version is optional, 1 to 128 characters without control characters. The whole object is at most 512 bytes. An invalid observation is refused with 400 and invalid_definition_observation, before any decision work, so nothing is recorded or counted. An observation for an asset with no pin, for an unregistered asset, or with a different canon than the pin has no effect.

If the pin cannot be read​

If the control plane cannot read the pin while handling a call, it treats the call as having no pin and continues. An unreadable pin never newly blocks a call. The same applies to an unreadable mode setting.

Audit​

EventWhenFields
asset.definition.pinnedA pin is set, changed or removedOrganization, actor, asset ID, action (set or removed), digest, canon, and the previous digest when there was one
asset.definition.changedA call carried a digest that differs from the pinOrganization, asset ID, pinned digest, observed digest, server version when given, operation ID when valid, transport, time

The pin event is written in the same transaction as the change. The changed event is written by a background worker shortly after the call, best effort: if recording fails the call is handled as described above, so an event can be missing. It is written once for each distinct pair of pinned and observed digest, so repeating a call adds nothing. Because the observed digest comes from the caller, at most 20 distinct observed digests are recorded for one asset and pinned digest; further ones are not recorded, and the strict deny is not affected. The events hold digests only, never a description, a schema or arguments. They are not exported to write-once storage and trigger no notification or webhook.

Limits​

  • One pin per asset, on mcp_tool assets only.
  • Observation: at most 512 bytes; server_version at most 128 characters.
  • At most 20 distinct observed digests recorded per asset and pinned digest.
  • The MCP adapter keeps at most 4096 tools per session and ignores a tool list entry larger than 1 MiB.

See also Enforcement Modes, MCP Adapter, Kill Switch, Reason Codes and Audit.