[ASI02] MCP tool-name pinning / typosquat-resistant resolution — close ASI02 #7

[initializ-mk]

Problem

If MCP tool names resolve ambiguously or by loose matching, a typosquatted or shadowing tool can intercept a call the agent intended for a legitimate tool. A related case: a server keeps the same tool name and version but silently swaps the tool's input/output contract underneath the agent.

Current state

Egress and denied_tools/max_tool_count policy strongly bound tool use (forge-core/security/platform_policy_enforce.go:194,228), and tool calls are audited (tool_exec). But MCP tool names are not version-pinned, ambiguous resolution is not proven to fail closed, and there is no check that a resolved tool's capability schema is the one the agent was built/authorized against. See docs/security/owasp-asi-conformance.md (ASI02 #7).

Proposed control

• Fully-qualified, version-pinned MCP tool identifiers, expressed as a structured resolution record ({server, namespace, name, version, capability_schema_hash}) rather than a single URI scheme — to avoid format-parsing/versioning overhead and stay aligned with MCP's own tool-identity conventions.
• Ambiguous resolution (more than one candidate) fails closed with an audit event rather than picking a candidate.
• Capability-schema-hash pinning: fail closed when a resolved tool's input/output schema hash drifts from the pinned value — catches the same-name/same-version contract-swap case, not just differently-named shadow tools. (Thanks to @0xbrainkid for this addition — see discussion below.)

Acceptance criteria

• A tool reference that resolves to more than one candidate fails closed with an instrumented event.
• MCP tools are addressed by a fully-qualified, pinned identifier ({server, namespace, name, version, capability_schema_hash}).
• A resolved tool whose capability-schema hash differs from the pinned value fails closed with an instrumented event (contract-swap defense).

Conformance test

• TestASI02_AmbiguousMCPToolFailsClosed — multi-candidate resolution fails closed.
• TestASI02_MCPToolSchemaDriftFailsClosed — same name+version, changed schema hash, fails closed.

Out of scope

• Server/issuer identity + attestation — that is the ASI04 supply-chain lane; the pinned identifier here deliberately does NOT carry issuer/server-identity material. Cross-reference, don't merge.
• Per-agent authority scope — authorization is ASI03 (identity & privilege abuse), not tool-name resolution. Cross-reference, don't merge.
• MCP server trust/attestation generally; non-MCP builtins.

Guideline reference

ASI02 mitigation #7 (OWASP Agentic Top 10 2026).

[0xbrainkid]

Useful boundary. I would keep the ASI02 control separate from server attestation, as you noted, but make the pinned identifier carry enough identity material for the runtime to audit later.

One possible shape:

mcp://{issuer}/{server_id}/{tool_namespace}/{tool_name}@{version}#{capability_schema_hash}

Then fail closed if any of these drift:

• issuer / server identity
• tool namespace + tool name
• pinned version
• capability schema hash
• authority scope for the calling agent

The distinction matters: tool-name pinning prevents a shadow tool from winning resolution. Identity + receipts make the dispatch auditable after the fact.

That is the layer we are building toward with AgentFolio/SATP: AgentFolio as the public agent/profile surface, SATP as the RC-S6 on-chain identity and receipt rail. Not a replacement for this ASI02 control, but a useful downstream invariant:

no MCP tool execution without a pinned tool id + verified agent/server identity + audit receipt

[initializ-mk]

Thanks — useful distinction, and I've folded part of it in.

The capability schema hash is a good addition, so I've added it to the control. Name + version pinning stops a differently-named shadow tool from winning resolution, but a schema hash also catches a server that keeps the same name and version and swaps the tool's input/output contract underneath the agent. The issue now has "fail closed on capability-schema-hash drift" in the acceptance criteria plus a TestASI02_MCPToolSchemaDriftFailsClosed conformance test.

On the rest, I'd like to keep this ticket tightly scoped so it stays shippable, and hold two of the fields out of the pinned identifier:

• Issuer / server identity is attestation — that's the ASI04 supply-chain lane. I'll cross-reference it there rather than bake server-identity material into this identifier.
• Per-agent authority scope is authorization — ASI03 (identity & privilege). Also cross-referenced, not merged.

Folding resolution + attestation + authorization into one identifier couples three concerns that each want to land independently; keeping them separate is what makes each shippable. I've also noted a preference for a structured resolution record ({server, namespace, name, version, capability_schema_hash}) over a single URI scheme, to avoid format parsing/versioning overhead and to stay aligned with MCP's own tool-identity conventions.

On the invariant "no MCP tool execution without a pinned id + verified identity + audit receipt" — agreed in spirit. The audit-receipt half is already being addressed locally: Forge's audit stream is getting tamper-evidence via hash-chaining (#212) and Ed25519 per-event signing (#213), so dispatch is provable after the fact without an external rail. So I'd keep this ASI02 control runtime-local and provider-neutral. AgentFolio/SATP would sit downstream as a consumer of those signed receipts rather than a dependency of the control here — happy to discuss that integration as a separate thread.