UCP Capability Discovery Explained
> UCP capability discovery is the process by which an AI agent queries a merchant's `/.well-known/ucp` manifest — a machine-readable JSON file at a standardised URL — to learn which commerce capabilities the merchant supports before attempting any interaction such as search, cart, checkout, or identity linking.
---
What Is UCP Capability Discovery?
Capability discovery is the first step in every UCP interaction. Before an AI agent can search a merchant's catalog, add items to a cart, or initiate checkout, it needs to know whether the merchant supports those capabilities at all. In the traditional web model, this question does not have a programmatic answer — an agent would have to attempt each interaction and handle failures. UCP solves this with a declarative discovery mechanism: the `/.well-known/ucp` manifest.
The `/.well-known/ucp` endpoint is a JSON file that every UCP-enabled merchant publishes at a standardised, predictable location on their domain. Its location follows IETF Well-Known URI conventions (RFC 5785), which defines `/.well-known/` as the standard path for host-level metadata — the same convention used by `/.well-known/acme-challenge` for TLS certificates and `/.well-known/security.txt` for security contact information. By placing the UCP manifest at this well-known path, any agent platform can reliably find it for any merchant domain without prior knowledge of the merchant's API structure.
The manifest is the complete declaration of what a merchant can do within the UCP protocol. An agent that reads it knows immediately: which UCP capabilities are supported, what endpoint URLs to call for each capability, which version of the UCP specification is in use, what payment handlers are configured, and what public keys are used for request signature verification. This gives agents everything they need to begin a UCP interaction without any out-of-band configuration.
---
How the Manifest Works
The UCP manifest is a JSON document served over HTTPS at `/.well-known/ucp` on the merchant's domain. It is read-only and publicly accessible — no authentication is required to fetch it, because its purpose is to advertise capabilities, not to expose sensitive data.
Core manifest fields:
| Field | Description | |---|---| | `ucp_version` | The UCP specification version the merchant implements | | `business_server_url` | The base URL of the merchant's UCP business server | | `capabilities` | Array of declared capabilities (e.g., `catalog_search`, `catalog_lookup`, `cart`, `checkout`, `identity_linking`) | | `services` | Object mapping each capability to its endpoint URL and supported methods | | `payment_handlers` | Array of configured payment methods (e.g., Google Pay) with associated merchant IDs | | `public_key` | The merchant's public key for verifying signed requests | | `profile` | Reference to the merchant's UCP profile declaration |
The `capabilities` array is the core of the manifest. It is the machine-readable list of what the merchant supports. Agents read this array and compute the intersection with what they are capable of invoking — the "server-selects" negotiation algorithm described in the UCP specification. If the manifest declares `catalog_search` but not `cart`, the agent will query the catalog but will not attempt to create a cart session.
Example capability declarations:
- `catalog_search` — the merchant's Catalog Search API is available
- `catalog_lookup` — the merchant's Catalog Lookup API is available
- `cart` — the merchant's Cart API is available for multi-item session management
- `checkout` — the merchant's Checkout Session API is available (native path)
- `redirect_checkout` — the merchant supports redirect-based checkout
- `identity_linking` — the merchant supports OAuth 2.0 identity linking
The Discovery Flow
The capability discovery flow follows three steps:
Step 1: Agent fetches manifest. The agent sends a `GET` request to `https://{merchant-domain}/.well-known/ucp`. The merchant's server returns the JSON manifest with a `200 OK` response. If the merchant does not have a UCP implementation, the server returns `404 Not Found` and the agent does not attempt further UCP interaction.
Step 2: Agent parses capabilities. The agent reads the `capabilities` array and computes the intersection with the capabilities it can invoke. This intersection defines the scope of possible interaction between the agent and the merchant for the current session. A merchant declaring `catalog_search`, `catalog_lookup`, and `redirect_checkout` will support discovery, evaluation, and redirected purchasing — but not native checkout or identity linking.
Step 3: Agent resolves endpoint URLs. Using the `services` object in the manifest, the agent resolves the specific endpoint URL for each capability it intends to invoke. These URLs point to the merchant's UCP business server — typically under a consistent path structure — and are the actual HTTPS endpoints the agent will call for search, lookup, cart, and checkout operations.
---
Why the Well-Known URI Matters
The choice of `/.well-known/ucp` as the manifest location is intentional and significant. Well-known URIs are a standards-based mechanism for host-level metadata. By placing the UCP manifest at this path, the protocol achieves several properties simultaneously:
Predictability. Any agent can find the UCP manifest for any domain without prior knowledge, configuration, or a directory lookup. The URL is always `/.well-known/ucp` — no registration, no discovery service required.
Crawlability. Search engines and agent crawlers that index well-known URIs will naturally index UCP manifests as part of standard web crawling, improving merchant discoverability without any additional submission step.
Consistency with web standards. Using an IETF-defined mechanism signals to the developer community that UCP is building on established web infrastructure rather than inventing proprietary discovery mechanisms.
---
Why It Matters for Merchants
Capability discovery is the gateway to UCP participation. A merchant without a `/.well-known/ucp` manifest is not discoverable by UCP-compatible agents — they are effectively invisible to this protocol layer regardless of how well their website performs in traditional search.
Publishing a manifest with even a minimal capability declaration — for example, just `catalog_search` — immediately makes the merchant queryable by AI agents that use UCP for product discovery. From that baseline, capabilities can be added progressively: lookup, cart, redirect checkout, native checkout, identity linking. Each addition expands the scope of what agents can do with the merchant's store.
The manifest is also the mechanism by which merchants stay in control of their UCP surface. A merchant who wants to pause a capability — for example, temporarily disabling cart creation during a system migration — updates the manifest to remove `cart` from the capabilities array. Agents reading the updated manifest will stop attempting cart operations until the capability is re-declared.
---
FeedBridge Relevance
FeedBridge generates and manages the `/.well-known/ucp` machine-readable manifest as a live platform capability. Merchants using FeedBridge have their UCP capability declarations managed through the UCP Dashboard Hub, which provides a compliance scorecard and capability checklist that maps directly to the manifest contents. The API Playground in FeedBridge allows merchants to test Catalog Search, Catalog Lookup, and Cart API responses — the three capabilities most commonly queried by agents after reading the manifest — in-dashboard before those endpoints are live for agent consumption.
FeedBridge's Protocol Compliance dimension in the AI Readiness Score (30% of total score) validates whether the manifest and the protocol endpoints it declares are correctly configured and returning valid responses. Merchants can review compliance status per capability in the FeedBridge dashboard.
---
Frequently Asked Questions
Q: Does the `/.well-known/ucp` manifest need to be updated manually? A: For merchants using FeedBridge, the manifest is managed by the platform and updated automatically when capabilities are added or modified through the UCP Dashboard Hub. For merchants managing their own UCP implementation, the manifest is a static JSON file that must be updated manually whenever the merchant's capability set changes.
Q: What happens if an agent fetches the manifest and it is stale? A: If the manifest declares a capability whose endpoint is not functioning, the agent will receive an error when it attempts to invoke that capability. The manifest and the underlying endpoints must be kept in sync. A declared capability with a broken endpoint is worse than an undeclared capability — it causes active failures rather than graceful non-invocation.
Q: Can I declare capabilities in the manifest that I have not fully implemented yet? A: No. Declaring a capability in the manifest signals to agents that the endpoint is available and functioning. Declaring an unimplemented capability will cause agents to receive errors on invocation, which degrades the merchant's reliability standing with agent platforms. Only declare capabilities that are fully implemented and tested.
Q: Is the `/.well-known/ucp` manifest indexed by Google? A: Google uses the manifest as part of the UCP onboarding process for Google AI Mode. Merchants who register their `/.well-known/ucp` URL through Google Merchant Center as part of UCP onboarding have their capability declarations verified by Google before their products become eligible for AI-assisted purchasing on Google surfaces.
Q: How does the public key in the manifest work? A: The `public_key` field in the manifest is the merchant's public key for signature verification. Agent platforms use this key to sign their requests to the merchant's UCP endpoints (in the `Signature` header). The merchant verifies each inbound request's signature against this public key to confirm the request originated from an authorised agent and has not been tampered with in transit.
---
Related Topics
Parent hub: UCP Technical
Related concepts:
- What Is UCP?
- UCP Across the Full Shopping Journey
- UCP Compatibility with A2A, AP2, and MCP
- UCP Profile and Capability Negotiation Basics
Breadcrumb:
---
Source Documentation
| Claim | Source | Source Class | Reference | |---|---|---|---| | `/.well-known/ucp` manifest structure and capability declarations | Google Developers Blog UCP / ucp.dev | T1 – Official UCP Docs | https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/ | | Server-selects capability negotiation algorithm | Google Developers Blog UCP | T1 – Official UCP Docs | https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/ | | IETF Well-Known URI conventions (RFC 5785) | a2aprotocol.ai UCP guide | T1 – Official UCP Docs | https://a2aprotocol.ai/blog/2026-universal-commerce-protocol | | FeedBridge: manifest generation, UCP Dashboard Hub, API Playground, Protocol Compliance score | FeedBridge Platform Capabilities April 2026 v2.0 | T1 – FeedBridge Internal | FeedBridge-Platform-Capabilities-April2026.md |