From fea8c0b4536d8d08c6f90ff8f69114b7ad7808c8 Mon Sep 17 00:00:00 2001 From: YanisMtcr Date: Sat, 29 Aug 2026 15:05:03 +0200 Subject: [PATCH] docs: clarify the idempotency-key server contract in the checkout MCP binding The MCP binding requires meta["idempotency-key"] on complete_checkout and cancel_checkout but never states what the server does with it. The REST binding and signatures.md carry the full contract; this adds the missing cross-reference in the MCP binding rather than restating it. --- docs/specification/shopping/checkout/mcp.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/specification/shopping/checkout/mcp.md b/docs/specification/shopping/checkout/mcp.md index d0f281c94..ea8fa0321 100644 --- a/docs/specification/shopping/checkout/mcp.md +++ b/docs/specification/shopping/checkout/mcp.md @@ -109,6 +109,19 @@ The `meta["ucp-agent"]` field is **required** on all requests to enable `meta["idempotency-key"]` for retry safety. Platforms **MAY** include additional metadata fields. +### Idempotency + +`complete_checkout` and `cancel_checkout` are state-changing operations and +**MUST** carry `meta["idempotency-key"]` (see [Request Metadata](#request-metadata)). +Servers **MUST** apply the same idempotency contract as the REST binding +([Specific Header Requirements](rest.md#specific-header-requirements)): +store the key with the operation result, return the cached result for a duplicate +key whose request matches the original, and treat a key reused with a mismatched +request as a conflict. Over MCP that conflict surfaces as the JSON-RPC error the +[error registry](../../overview/index.md#error-handling) maps from HTTP `409` (`-32000`). See +[Message Signatures — Replay Protection](../../signatures.md#replay-protection) for the +full payload-matching contract. + ## Tools UCP Capabilities map 1:1 to MCP Tools.