Lesson 03
tools/list returns transactional metadata under _meta["org.agenttxprotocol/transaction"]. Catalogs may also carry the alias x-atp-transaction. The proxy copies the signed definition into _meta. It does not authorize a call from either annotation. If the manifest does not name the tool, the call does not run.
The compatibility shape lives in spec/examples/transfer-inventory.tool.json. The forward call moves stock. The compensation calls the same tool with the warehouses swapped and a new transfer id.
{
"reversibility": "COMPENSATABLE",
"idempotencyKeyPath": "$.input.transfer_id",
"compensation": {
"tool": "transfer_inventory",
"argumentMapping": {
"transfer_id": "'comp_' + input.transfer_id",
"sku": "input.sku",
"qty": "input.qty",
"source_wh": "input.target_wh",
"target_wh": "input.source_wh"
},
"maxRetries": 5,
"onCompensationFailure": "ESCALATE_HITL"
}
}
Mapping values are expressions. They can read input, output, and tx.id. There is no I/O. A COMPENSATABLE tool with an empty mapping is rejected when the manifest is opened.
After the caller’s arguments pass schema validation, the engine injects:
idempotency_key = txId + ":" + stepIndex + ":" + sha256(canonical(arguments)).substring(0, 32)
The hash covers the arguments before the key is added, so a schema with additionalProperties: false still accepts the payload the agent sent. idempotencyKeyPath is stored beside that key as a business identifier. A dotted path deeper than one field is ignored. Compensation uses comp: plus the forward key plus the attempt number, and that value overwrites any mapped idempotency_key.
The client supplies txId, 1 to 80 characters from [A-Za-z0-9_.:-]. The same id and the same plan hash returns the recorded result. The same id with a different plan is AtpIdempotencyConflict (−31807).
The document is { payload, signature }. The signature is Ed25519 over the canonical JSON of payload. Canonical form sorts object keys, emits no insignificant whitespace, and writes 10 rather than 1E+1.
java -jar mcp-tx-proxy/target/tx-engine.jar keys java -jar mcp-tx-proxy/target/tx-engine.jar sign --kid admin --private <base64> --payload manifest.json
The payload needs manifestId, a non-empty tools array, and optional rules. Each tool has name, an object inputSchema, and a transaction object. The adapter is oltp, lakehouse, or api. An API tool with dry-run left on must include a dryRunExample object. Dry-run defaults to true unless the boolean false is set.
onFail is neither DENY nor PAUSE rejects the whole manifest. The engine does not start with a half-trusted catalog.