Universal Commerce Protocol (UCP): a specification repo, not an SDK

What UCP actually is, and who the repository is for

The README states the project "addresses a fragmented commerce landscape by providing a standardized common language and functional primitives." That sentence is the whole pitch. The problem it names is the cost of one-off integrations between platforms (the README lists "AI agents and apps"), businesses, Payment Service Providers and Credential Providers. Each new pairing otherwise needs its own contract.

The audience follows from that. This is not a repository for someone who wants to add a checkout button to a store. It is for people implementing or reviewing a protocol: platform engineers wiring an agent to merchant backends, PSP engineers handling token exchange, and standards contributors editing schemas. The repository itself is the specification and its documentation site, with Python and Node tooling around the edges. If you are looking for a runtime library, the README points elsewhere, to separate SDK, samples and conformance repositories under the same GitHub organisation.

One structural detail matters more than it looks. pyproject.toml sets "packages = []" under [tool.setuptools]. There is no importable ucp module here. The Python dependency group is documentation tooling: mkdocs-material, mkdocs-macros-plugin, mike for versioned docs, yamllint, datamodel-code-generator. Read that as a statement of intent. The artifact is the spec, and the code exists to publish it.

Capabilities, extensions and dynamic discovery

The architecture the README describes is composable rather than monolithic. Commerce is broken into Capabilities, named as "Checkout", "Identity Linking", "Order" and "Payment Token Exchange" in the initial release, and Extensions such as Discounts and Fulfillment that layer on top. The stated reason for the split is to avoid "bloating the capability definitions": a business that does not offer discounts should not have to parse discount fields.

Discovery is the second half. Businesses "declare their supported Capabilities in a standardized profile", and platforms then configure themselves against that profile. This is what makes the protocol agent-oriented. An agent that has never seen a given merchant can read the profile and decide what it is allowed to attempt, instead of being hardcoded per merchant.

The transport story is deliberately loose. The README says UCP is "transport agnostic" and that businesses can offer capabilities via REST APIs, MCP (Model Context Protocol) or A2A. That is a real design choice with a real cost: the spec has to define semantics that survive three different wire formats, and an implementer still has to pick one and get its details right. Transport agnosticism removes a constraint on adopters; it does not remove work from them.

On security, the README points to "AP2 mandates and verifiable credentials" and says UCP builds on existing open standards for payments, identity and security "rather than reinventing the wheel". Identity Linking specifically uses OAuth 2.0 to let a platform act on a user's behalf. Order updates arrive as webhooks for shipped, delivered and returned events.

Installing the tooling and linting a schema change

The README's Getting Started section sends readers to ucp.dev for the specification and to separate repositories for samples, SDKs and conformance tests. What it documents in-repo is contributor setup. Schemas live in source/ and are published with ucp_* annotations intact; the ucp-schema tool resolves those annotations at runtime so an agent can generate operation-specific variants (create, update, read) and only process fields relevant to the current action and direction.

Install ucp-schema first. The README gives two routes, from crates.io or from git:

cargo install ucp-schema                 # from crates.io
cargo install --git https://github.com/universal-commerce-protocol/ucp-schema  # from git

After editing JSON files in source/, validate syntax and references before anything else:

ucp-schema lint source/

Expect lint failures to name the file and the broken reference. This is the cheapest feedback loop in the repository, and it runs without the documentation stack.

For the site itself, the project uses uv for Python dependency management. The README's sequence is to sync dependencies, run the development server with a watch on source/, and open the local address:

uv sync
uv run mkdocs serve --watch source

The README says to open http://127.0.0.1:8000 in your browser. Before submitting, it specifies a strict build that fails on warnings or errors:

uv run mkdocs build --strict

There is also a local build script, ./scripts/build_local.sh, which the README describes as building the full site including spec versions and starting a local server. That is the route to use when a change touches versioned content, since the plain serve command does not build spec versions.

Where UCP is the wrong tool

The most concrete limitation is that this repository will not complete a purchase for you. Nothing in the README describes a hosted service, a reference server, or a runnable endpoint. The initial release "focuses on the essential primitives for transacting", and the primitives are specifications. If your goal is to accept payments next week, an established payment integration will get you there faster, and UCP will not.

The second limitation is the specification's own maturity. The README calls this the "initial release", and the release cadence visible in the tags is roughly quarterly: v2026-01-23, v2026-04-08, v2026-08-25. A quarterly cadence on a young standard means implementers should expect the surface to move. There is no compatibility or deprecation policy in the README, and the README does not document rollback or migration between spec versions. Treat that silence as a question to raise in the project's GitHub Discussions before you build against a specific tag.

Third, transport agnosticism cuts both ways. A team that only ever needs REST gets no benefit from MCP or A2A support and inherits the ambiguity of a spec that must accommodate all three. And the capability list is short by design. If your commerce flow depends on something outside Checkout, Identity Linking, Order and Payment Token Exchange, the README gives no indication of when it arrives.

Finally, the version metadata is inconsistent in a way that affects pinning. pyproject.toml declares version 2026.01.23, while the newest release tag is v2026-08-25. Anyone resolving the package rather than the tag will get a version string that does not match the release they think they are on.

UCP and ACP: two answers to agentic checkout

The obvious comparison is the Agentic Commerce Protocol (ACP), which also targets agent-driven purchasing. The difference visible here is in scope and in where the boundary sits.

UCP is framed as a multi-party standard. Its named participants are platforms, businesses, Payment Service Providers and Credential Providers, and it defines capabilities for each relationship: Checkout for the cart and tax flow, Identity Linking for delegated authorization over OAuth 2.0, Order for webhook lifecycle events, and Payment Token Exchange for PSP and credential-provider token handling. It also specifies a discovery profile, so a platform can learn what a business supports without prior coordination. And it is explicitly transport agnostic across REST, MCP and A2A.

That breadth is the trade-off. A standard that must serve four participant types and three transports carries more surface area than one scoped to a single agent-to-merchant checkout path. If your only requirement is an agent completing a purchase against one merchant, the narrower protocol will likely be less to implement. If you are a PSP or credential provider, or you need capability discovery across many merchants, UCP's structure is the reason to look at it. The README does not compare itself to ACP, so the difference above is drawn from what UCP states about itself, not from a side-by-side the project publishes.

Licence, maintenance and the cost of tracking a quarterly spec

The repository is Apache-2.0, and the README's file header carries the standard Apache grant with the URL to the licence text and the note that the software is distributed "on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND". For a specification repository, the practical question is narrower than for a code dependency: the licence permits use and modification of the schema and documentation sources, but it says nothing about patent or trademark terms for the protocol itself, and the README does not address either. If your organisation needs that clarity, it is a question for the project's Discussions rather than something to infer from the LICENSE file. This is not legal advice.

Maintenance is visible and recent. The repository is not archived, and the last push was on 2026-09-23, the same day as the most recent release tag's month. Three release tags appear in 2026: v2026-01-23, v2026-04-08 and v2026-08-25. That is a steady cadence, and the tooling around it is conventional: pre-commit hooks, prettier, stylelint, biome, cspell, yamllint and a strict MkDocs build. The upgrade cost for a spec consumer is the cost of re-reading a changed schema and regenerating whatever you derive from it. The repository ships datamodel-code-generator as a dev dependency, which suggests generated models are part of the intended workflow, though the README does not document a generation command.

Contributors carry the usual documentation-repo overhead: two package managers (uv for Python, yarn for Node, pinned as [email protected]), a strict build that fails on warnings, and a lint step that must pass before schema changes land.

Editorial conclusion

Adopt UCP if you are building a platform, PSP or credential provider that needs a declared, discoverable commerce interface rather than another bespoke integration, and if you can implement the protocol yourself from the schemas. Do not adopt it expecting a drop-in Python package: pyproject.toml declares no runtime packages, and the repository is documentation and schema source. Before committing, verify three things in the spec: which capabilities the current release actually covers, how your transport (REST, MCP or A2A) maps onto them, and whether the conformance tests cover the flows you need. The version string in pyproject.toml, 2026.01.23, trails the v2026-08-25 release tag, so pin against the tag rather than the package metadata.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Universal-Commerce-Protocol/ucp on GitHub