UCP Discovery Mechanism Diagram

How to Configure the /.well-known/ucp Discovery Endpoint for AI Agents

Key Takeaways (Nov 8, 2026 refresh): The /.well-known/ucp profile is the mandatory programmatic front door — businesses MUST host it at /.well-known/ucp [Sheet 1]. Current spec is v2026-08-25; Google’s merchant surfaces implement 2026-04-08. REST is the recommended default; stateless MCP is Early Access Beta. Request authentication is RFC 9421 ES256 signatures + mTLS, not headers — headers are routing/analytics only. US direct checkout live (Oct 15, 2026 with Universal Cart); Canada shopper-side live Nov 4, 2026; Merchant Center self-serve 2027.

🎧 Listen to this article
Last Updated: November 10, 2026 • Autonomous Agentic Commerce Spec v2026-08-25

Production Validated

The Store’s Front Door for AI

Manifest Component Spec v2026-08-25 Directive Data Type Cryptographic Handshake & Validation Cache Directive Agentic Enforcement
Profile Root ucp.version SemVer / Date Root discovery manifest; RFC 9421 ES256 signature max-age=86400 Mandatory Front Door
Service Registry ucp.services URI Array REST endpoint routing; mTLS Root CA certificate check 300s TTL Automatic Failover
Payment Handlers ucp.payment_handlers Object Array Google Pay config / PAN_ONLY; FIDO AP2 network token check Per-session Strict PCI Isolation
Public Key Set keys[] JWK Set EC P-256 / Ed25519; Signature-Input header verification Refetch on unknown kid Anti-Spoofing Lock
Cart Interface dev.ucp.shopping.cart REST Resource Cart transfer & state sync; DPoP proof-of-possession token Real-time session Universal Cart Link
Agent Identifier UCP-Agent HTTP Header Platform routing & telemetry; must match signature identity Per-request Non-Auth Routing

As we move into the era of agentic commerce, the way stores communicate with the web is fundamentally changing. In the traditional web, a user visits a homepage and navigates via a GUI. In the universal commerce protocol (UCP) landscape, autonomous agents—such as Google’s Gemini or specialized Model Context Protocol (MCP) clients—need a programmatic way to understand your store’s capabilities without scraping raw HTML. The solution is the /.well-known/ucp discovery endpoint. This endpoint acts as the programmatic front door for AI, providing a structured REST API manifest that tells an agent exactly how to interact with your inventory, cart, and checkout processes.

Implementing this endpoint is the first and most critical step for any developer looking to integrate with the UCP ecosystem. [Author opinion] By serving a standardized JSON document at a predictable location, you transform your static web store into a machine-readable commerce node. [Author metaphor] This allows Gemini to query your store directly, fetch real-time availability, and even initiate a Native Checkout flow via Google Pay, all within the context of a natural language conversation. Unlike traditional crawlers that rely on robots.txt to know where not to go, the UCP discovery document tells agents exactly where to go and which protocols you support. [General engineering contrast, author voice]

November 2026 update: Spec v2026-08-25 is Latest (no March 2026 release ever existed). Google implements 2026-04-08. Launch surfaces are AI Mode in Search + Gemini web/mobile. Merchant remains Merchant of Record. Do not teach header/DNS identification as authentication (Oct 27-31 FAQ rewrite removed it). Canada is live for shoppers since Nov 4, 2026 — do not describe as future/planned.

JSON Schema Breakdown

The discovery document is a standardized JSON profile hosted at /.well-known/ucp that defines your store’s identity and its interface for catalog, cart, and checkout use cases. Businesses MUST host their profile at /.well-known/ucp, which serves as the mandatory programmatic front door for discovery. REST is the recommended default interface for these catalog, cart, and checkout interactions, with stateless MCP available as Early Access Beta requiring onboarding and testing.

The profile MUST include ucp.version (REQUIRED) and ucp.services and ucp.payment_handlers (likewise required), plus canonical keys[] JWK Set (EC P-256/P-384, OKP Ed25519) replacing legacy signing_keys[]. Capabilities are named {reverse-domain}.{service}.{capability}; dev.ucp.* reserved; capability version is YYYY-MM-DD.

The Capabilities Object

Checkout runs over REST (Merchant Center validation supports only REST). Payment handlers are advertised in ucp.payment_handlers with id, version, spec, schema, available_instruments, config; Google surfaces require Google Pay config in-profile and use PAN_ONLY. An embedded-checkout extension is shipped in v2026-08-25; cart transfer uses Cart API dev.ucp.shopping.cart.

In practice, this means Gemini and other surfaces can query your catalog for real-time availability and pricing, manage cart state through the documented Cart API, and then complete payment through an advertised payment handler such as Google Pay configured in-profile with PAN_ONLY. Because REST is the recommended default, merchants should prioritize a complete and correct REST implementation first, and treat stateless MCP as Early Access Beta functionality that requires separate onboarding and testing rather than an automatic extension of the profile.

The Endpoints Map

A diagram with a circle on the left connected by an arrow to a central rectangle, which branches into three parallel rectangles on the right, with a smaller key shape linked below and a dashed return path.

No products_url / cart_url / checkout_url / webhook_url / merchant_id / auth_config / native_checkout fields exist in the spec model. Discovery is GET /.well-known/ucp (carries no UCP-Agent header); platforms advertise their profile URI in UCP-Agent per-request; webhooks MUST be signed; verifiers MUST ensure authenticated identity matches UCP-Agent.

For developers, the operational takeaway is straightforward: host the complete v2026-08-25 profile at the exact well-known path, include the required ucp.version, ucp.services, and ucp.payment_handlers objects with correctly named capabilities in the form {reverse-domain}.{service}.{capability}, and publish your canonical keys[] JWK Set for signature verification. Discovery itself is a simple GET to the well-known URI, and per-request platform identification is carried in UCP-Agent for routing and analytics — never as authentication.

CORS and Security Headers

A diagram showing a solid two-part gate with a bold arrow passing through it, and a separate dashed line going around the gate to rejoin on the other side.

Security is equally paramount. As general best practice, serve the discovery endpoint over HTTPS. [General practice] While the discovery document itself is public, the REST API endpoints it points to should be protected by OAuth 2.0.

Authentication mechanisms are API Keys, OAuth 2.0, mTLS, and HTTP Message Signatures (RFC 9421) — only signatures enable permissionless interaction. The only identity capability is dev.ucp.common.identity_linking (OAuth-based). Verify ES256 signatures in Signature / Signature-Input against keys in https://ucp.goog/.well-known/ucp.json; mTLS against Google UCP Root CAs; do not cache longer than Cache-Control max-age=86400; on unknown kid refetch before rejecting. Never authenticate on UCP-Agent / User-Agent alone; health checks use User-Agent: Google-UCP-Prober/1.0.

This signature-based model is intentional. Request authentication under UCP is RFC 9421 ES256 signatures plus mTLS, not headers. Headers such as UCP-Agent and User-Agent are for routing and analytics only, and must not be treated as authentication. Verifiers must check that the authenticated identity matches the claimed UCP-Agent, that webhooks are signed, and that key material is refreshed according to cache directives, refetching on unknown key IDs before rejecting a request.

Validation and Testing Tools

Once you have deployed your JSON profile, it is vital to validate it against the UCP core schema for v2026-08-25. Confirm that ucp.version, ucp.services, and ucp.payment_handlers are present and correctly structured, that capabilities follow the {reverse-domain}.{service}.{capability} naming with YYYY-MM-DD versions, that Google Pay configuration is present in-profile where Google surfaces are targeted with PAN_ONLY, and that your canonical keys[] JWK Set is published and consistent with the signatures you emit.

Testing should cover the full REST journey for catalog, cart, and checkout, including Cart API dev.ucp.shopping.cart for cart transfer where applicable, and the embedded-checkout extension shipped in v2026-08-25 where you intend to support it. Because Merchant Center validation supports only REST, ensure your REST implementation is complete before pursuing stateless MCP, which remains in Early Access Beta and requires onboarding and testing.

Integrating with Model Context Protocol (MCP)

For developers building more complex agentic experiences, it is important to understand the current platform status: REST is the recommended default, and stateless MCP is Early Access Beta. MCP-based experiences therefore require onboarding and testing and should not be treated as automatically available from the profile alone.

Where MCP is in scope, focus on correct REST coverage first, correct payment-handler advertisement with id, version, spec, schema, available_instruments, config, and correct signature and mTLS handling. Launch surfaces for Google checkout are AI Mode in Search plus Gemini web and mobile, with the merchant remaining Merchant of Record throughout. US direct checkout is live since Oct 15, 2026 with Universal Cart, and Canada is live for shoppers since Nov 4, 2026.

Native (UCP) integration does not influence product ranking; UCP-integrated offers feature the direct purchase option. Simplified UCP integration in Merchant Center broadens next year — self-serve is a 2027 item, not live shopper-side checkout (US live Oct 15, 2026; Canada shopper-side live Nov 4, 2026 via lululemon, select Shopify merchants, Shoppers Drug Mart, Simons; retailer remains seller of record).

Discovery Endpoint Architecture FAQ

Why is /.well-known/ucp mandatory rather than a custom merchant API route?

Hosting at the standardized /.well-known/ucp path ensures autonomous AI agents can discover store capabilities, payment handlers, and cryptographic keys without requiring prior out-of-band configuration or brittle web scraping.

How does RFC 9421 HTTP Message Signing protect UCP discovery endpoints from tampering?

RFC 9421 ES256 signatures cryptographically bind each request to the caller’s verified public key, preventing man-in-the-middle attacks, unauthorized prompt modifications, and request forgery across open agentic networks.

What is the difference between UCP-Agent header routing and cryptographic request authentication?

The UCP-Agent header is strictly for platform telemetry and routing. Authentic caller identity is established solely via RFC 9421 digital signatures and mutual TLS against verified Google Root CAs.


Posted

in

by

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *