Skip to content

Protocol mapping: Model Context Protocol (MCP)

MCP lets a tool declare behavioural annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) on a tools/list definition. The MCP specification is explicit that these are unenforced hints: "For trust & safety and security, clients MUST consider tool annotations to be untrusted unless they come from trusted servers" (MCP tools page, spec revisions 2025-06-18 and 2025-11-25). An annotation is not an authorization construct.

The NAALP-MCP binding profile (the draft's Foreign Carriage by Class section) maps that untrusted hint to a signed effect claim by a named key, enforced fail-closed — without inventing a new envelope, encoding, signature, identity, or audit mechanism. An MCP tool call becomes an ordinary N-AALP object on the Bridge channel (0x000D), reusing the closed effect lattice, the approval + single-use consume ledger, and the content-id framing already defined for every other N-AALP object.

Reference implementation: ecosystem/naalp-mcp-bridge (Python), built directly on the Part-1 naalp.mcp / naalp.envelope / naalp.approval primitives — every cryptographic and wire operation is delegated to those, never re-derived. Mutation-tested.

What maps to what

MCP-native shape N-AALP wire object Carried how
A tools/list tool definition (JSON, with annotations) naalp-mcp-tool-call field 1 (tool, bstr) octet-for-octet, never re-serialized
A JSON-RPC 2.0 tools/call request's params.arguments naalp-mcp-tool-call field 2 (args, bstr) octet-for-octet, never re-serialized
The tool definition's annotations object naalp-mcp-annotations (map, keys 1-4) transcribed once, at the boundary (§ below)
— naalp-mcp-call-binding {1: tool_id, 2: args_id} derived; an approval binds this pair

naalp-mcp-tool-call is tier-1 Bridge-channel object, kind McpToolCall (1) — a named escalation over the frozen baseline Carriage kind (0). The wrapper's own effect is the envelope's normal effect field (field 7), not a body field.

The annotation transcription

The N-AALP spine has no CBOR boolean, so each JSON hint is carried as the uint 1 (true) / 0 (false) under naalp-mcp-annotations keys 1..4 (readOnly, destructive, idempotent, openWorld). An absent hint is distinct on the wire from a present 0 and takes its own MCP default when the effect mapping is computed.

The published annotation → effect mapping

The closed four-effect lattice (read_only < idempotent_write < non_idempotent_write < destructive) is reached by a published table (vectors/registry/mcp.csv), applying each hint's MCP default when the annotation is absent:

readOnlyHint destructiveHint idempotentHint → effect
true any any read_only
false true any destructive
false false true idempotent_write
false false false non_idempotent_write

destructiveHint defaults to true and readOnlyHint defaults to false, so a tool with no annotations at all maps to destructive — the fail-closed collapse to the most severe outcome, matching the spine rule that an absent effect on a state-changing object is destructive. openWorldHint is carried for accountability but never enters the effect mapping. An annotation set that would resolve outside the lattice is rejected MalformedAnnotation, never defaulted to benign.

The wrapping signer is accountable

The wrapper's declared envelope effect is under the wrapping signer's ML-DSA signature. A verifier independently recomputes the annotation-derived effect from the carried annotations and enforces the more severe of the two — a disagreement collapses up, never down, and is attributable to the wrapping signer's key. A signer that declares below its own tool's annotations is rejected fail-closed (EffectUnderDeclared): a lying tool cannot escape by wrapping a destructive action under a read_only declaration.

Approval binds the exact call

A per-call approval binds the content id of the (tool_id, args_id) call binding, reusing the existing approval + single-use consume ledger. A changed tool description or changed arguments yields a new call content id and invalidates any prior approval bound to the old one. The approval's granted effect must cover the call's enforced (more-severe) effect, must be unexpired, and is consumed exactly once.

Using the bridge

from naalp_mcp_bridge import carry_tool_call_from_objects, receive_tool_call, bridged_call_request
from naalp import cose, policy

# Exactly what an MCP client already holds: a tool definition from tools/list, and a
# JSON-RPC 2.0 tools/call request naming that tool and its arguments.
tool_definition = {
    "name": "transfer_funds",
    "description": "Transfer funds between two accounts",
    "annotations": {"readOnlyHint": False, "destructiveHint": True},
}
call_request = {
    "jsonrpc": "2.0", "id": 7, "method": "tools/call",
    "params": {"name": "transfer_funds", "arguments": {"to": "acct-778-441", "amount": 500000}},
}

signer_seed = bytes([0xC1]) * 32
signer_pk = cose.mldsa_keygen("ML-DSA-65", signer_seed)

carried = carry_tool_call_from_objects(
    tool_definition, call_request, signer_seed=signer_seed, created=1_800_000_000_000,
)
# carried.declared_effect / carried.annotation_mapped_effect are both `destructive` here.

# Later, standing alone, holding only the wire bytes and the signer's public key:
recv = receive_tool_call(carried.signed_object, cose.PROFILE_PUBLIC, cose.ALG_MLDSA65, signer_pk)
assert recv.tool_bytes == carried.tool_bytes           # octet-exact recovery
assert bridged_call_request(recv, rpc_id=7) == call_request   # the original JSON-RPC request, back
assert recv.enforced_effect == policy.DESTRUCTIVE

Two ingestion paths are offered: carry_tool_call / receive_tool_call operate on raw foreign octets — the literal bytes a tool-definition document and a call's arguments document had on the wire, the strictest form of octet-for-octet carriage; carry_tool_call_from_objects / bridged_call_request (used above) are the convenience layer for a caller holding already-parsed MCP objects — each object is serialized to canonical JSON bytes exactly once, at the ingest boundary, and those bytes are what is carried from then on.

A tampered signed object fails closed with a named error (BadSignature); an approval for a different call's argument set is rejected ApprovalRequired with no ledger append; a replayed (already-consumed) approval is rejected AlreadyConsumed. See ecosystem/naalp-mcp-bridge/examples/isolation_demo.py for the full runnable demonstration of all four properties.

Failure modes

Error kind When
MalformedAnnotation An annotation set maps outside the closed effect lattice
EffectUnderDeclared The wrapping signer's declared effect is below the annotation-mapped effect
EffectOutsideLattice The declared effect is not in {0..3}
ToolCallMalformed The body is not {1: tool, 2: args, 3: annotations}, or not a tier-1 Bridge McpToolCall
ApprovalRequired The approval does not bind the exact call, or under-grants the enforced effect
AlreadyConsumed The approval has already been spent
ForeignToolNotJSON / ForeignBodyNotJSON (bridge-only) The carried octets do not decode as UTF-8 JSON
ToolNameMismatch (bridge-only) A tools/call request names a different tool than the supplied definition

Every check is fail-closed: a failing object is rejected whole, returns its named error, and causes no state change. A baseline-only endpoint (validating only the frozen kinds) correctly rejects an McpToolCall as UnknownKind.

What this mapping does not decide

  • MCP transport and server discovery. How an MCP server is found or connected to is out of scope; this profile governs a carried tool call, not the MCP session.
  • A general foreign-annotation vocabulary. Only the four documented MCP behavioural hints are mapped here; another protocol's own hint vocabulary would need its own binding profile under the same carriage-not-adoption discipline.
  • Non-Go/Rust SDK ports. The profile is graded on the Go and Rust two-implementation parity path against a non-circular oracle; the Python bridge above is an ecosystem package built on the Python SDK, and porting the profile itself to the other reference SDKs is tracked in the parity ledger.

See also: the object model, effects and safety, and the A2A mapping for the sibling agent-coordination profile.