Skip to content

UCP overview

UCP (the Universal Commerce Protocol) is a spec describing how a commerce backend advertises what it can do — catalog, cart, checkout, order, and a handful of Portage-owned extensions — as a set of named capabilities (dev.ucp.shopping.cart, dev.ucp.shopping.checkout, and so on), each with a version and a list of actions. Portage is an implementation of both sides of that conversation in Ruby:

  • Server side (portage-ucp + an adapter gem): your backend implements a Portage::Ucp::Adapter subclass; the gem turns whichever methods you override into an advertised capability, a signed /.well-known/ucp manifest, and a set of MCP tools an agent can call. See Architecture for the full request path and Writing adapters for the Adapter contract itself.
  • Client side (portage-ucp-client): a shopper's agent discovers a manifest, connects over whichever transport it advertises (stdio, Streamable HTTP, or an in-process loopback for testing), and drives the same capability actions as tool calls. See the walkthrough for a full buy end to end.

UCP is deliberately capability-shaped, not platform-shaped: an agent doesn't need to know it's talking to Shopify vs. WooCommerce vs. a hand-rolled backend, only that dev.ucp.shopping.checkout is advertised and what actions it exposes. That's also why capability coverage varies by adapter — Etsy and Instagram, for instance, have no real cart/checkout API to back, so they only ever advertise catalog and a redirect-link checkout. The capability coverage page and the feature matrix both cover exactly which capability each bundled adapter can back for real, and why.

MCP (Model Context Protocol) is the transport UCP rides on in this project: Portage::Ucp::Mcp::Server.build turns an advertised capability's actions into MCP::Tool objects, served over stdio or Streamable HTTP via the mcp gem — or, via portage-ucp-webmcp, over a browser page's own document.modelContext instead of a separate server process (see the WebMCP adapter page).

Two more pieces worth knowing about before you go deeper:

  • The agent profile (meta.ucp-agent.profile) — a document describing the agent making a call, distinct from the manifest describing the business. See Agent profile.
  • /.well-known/ucp itself — why that path, how it differs from llms.txt, and what a platform's own native support (Shopify's Universal Commerce Agent app) already covers vs. leaves for this gem to fill in. See Serving /.well-known/ucp.

If a real UCP server starts rejecting every tool call with Tool not found once you attach an agent profile, that's almost always a capability-id mismatch between the profile and the server's registry, not a permissions problem — see the tool gating troubleshooting writeup, which documents a real, corrected investigation into exactly that failure mode.