Skip to content

docs: clarify the idempotency-key server contract in the checkout MCP binding - #679

Open
YanisMtcr wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
YanisMtcr:docs/mcp-idempotency-contract
Open

docs: clarify the idempotency-key server contract in the checkout MCP binding#679
YanisMtcr wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
YanisMtcr:docs/mcp-idempotency-contract

Conversation

@YanisMtcr

@YanisMtcr YanisMtcr commented Aug 3, 2026

Copy link
Copy Markdown

Motivation

The MCP binding requires meta["idempotency-key"] on complete_checkout and
cancel_checkout "for retry safety", but it does not state the server-side
idempotency contract. That contract is only spelled out in the REST binding
(Specific Header Requirements: store the key, return the cached result on a
matching retry, 409 on a mismatched reuse) and in the overview error registry
(409-32000).

An implementer building the MCP transport therefore has to cross-reference the
REST binding to learn how the server must behave on retries and key reuse. This
came up while implementing the checkout MCP binding: the requirement is
derivable, but not stated where an MCP-only reader would look.

What this PR changes

  • checkout-mcp.md - adds a short ### Idempotency subsection under
    Protocol Fundamentals (right after Request Metadata) that states the server's
    idempotency contract for the MCP transport by reference to the REST binding
    and the overview error registry, rather than restating it (to avoid a second
    source of truth that could drift).

No normative change: this documents behavior the spec already requires.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None.

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

@google-cla

google-cla Bot commented Aug 3, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

… binding

The MCP binding requires meta["idempotency-key"] on complete_checkout and
cancel_checkout but does not state the server-side idempotency contract, which
is only spelled out in the REST binding and the overview error registry. Add a
short Idempotency subsection that states it by reference, without restating the
full contract.
@YanisMtcr
YanisMtcr force-pushed the docs/mcp-idempotency-contract branch from fad50e3 to b22c9d6 Compare August 3, 2026 18:42
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation status:under-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants