Lesson 06
Every MCP method and every tx/* method requires protocol version 2026-07-28 and a client-capabilities object. The SDKs send both. You do not add an initialize handshake. The 2026-07-28 profile is stateless.
The package in sdks/python uses only the standard library.
from agent_tx import TransactionClient, compensatable_tool
@compensatable_tool(
"transfer_inventory", "Moves stock", {"type": "object"},
"transfer_inventory", {"sku": "input.sku"},
idempotency_key_path="$.input.transfer_id")
def transfer(sku):
return sku
client = TransactionClient("http://127.0.0.1:8080")
client.execute("tx-1", [{"tool": "reserve_credit", "arguments": {
"transfer_id": "a", "amount": 1
}}], "reserve before capture")
The decorator publishes both _meta and the x-atp-transaction alias. That advertisement still has to match a signed manifest on the server. execute, resume, abort, status, replay, and tools are the methods. A JSON-RPC error becomes TransactionError.
TxClient client = new TxClient("http://127.0.0.1:8080/");
Map<String, Object> snap = client.execute("sdk-1", List.of(Map.of(
"tool", "reserve_credit",
"arguments", Map.of("transfer_id", "sdk", "amount", 1))), "sdk");
client.replay("sdk-1", 1);
ToolMetadata.compensatable builds the same advertisement map. A trailing slash on the base URL is stripped before /mcp is appended.
Point a Spring AI 2.1 Streamable HTTP client at http://127.0.0.1:8080/mcp. This repository does not embed Spring. If the Accept header contains text/event-stream, the proxy answers with one Server-Sent Event. Otherwise the body is application/json.
java -jar mcp-tx-proxy/target/tx-engine.jar stdio
STDIO is one JSON object per line. Blank lines are ignored. The methods are server/discover, tools/list, tools/call, tx/execute, tx/resume, tx/abort, tx/status, tx/replay, and tx/ledger.
tools/call is a one-step execute. isError stays false when the saga finishes, including a clean rollback. Read structuredContent.state. Use tx/resume when that state is ESCALATED_HITL.The state reference lists every legal edge. The error reference lists the −31801 through −31812 codes.