/.well-known/ucp Endpoint: Universal Commerce Protocol

Introduction to Universal Commerce Protocol Discovery

In the evolving landscape of agentic commerce, the ability for Large Language Models (LLMs) and autonomous agents to discover and interact with e-commerce infrastructure is paramount. The /.well-known/ucp endpoint serves as the foundational discovery mechanism for the Universal Commerce Protocol (UCP). Following the conventions established by RFC 8615, this endpoint provides a standardized, machine-readable entry point that allows agents—such as Google Gemini—to identify a merchant’s capabilities, supported payment gateways like Google Pay, and the specific Model Context Protocol (MCP) servers available for deep integration.

JSON Schema for UCP

The core of the /.well-known/ucp endpoint is a JSON document that defines the technical interface of the store. This schema is designed to be extensible, supporting both current REST API patterns and future agentic workflows. Developers must ensure the JSON response adheres to the following structural definition.

Top-Level Object Properties

Defining Checkout Paths

The capabilities array informs the agent whether it can complete a transaction entirely via API (Native Checkout) or if it must hand off the user to a secure web view (Embedded Checkout). For Google-centric implementations, a native checkout path often requires integration with the Google Pay API for secure credential handling. When ‘native_checkout’ is advertised, the agent expects a specific set of REST API endpoints to be available for cart creation, shipping estimation, and payment submission.

Example Payload

{ "v": "1.0.0", "merchant_id": "gmc_123456789", "capabilities": ["native_checkout", "inventory_query"], "endpoints": { "base_url": "https://api.example.com/ucp/v1", "mcp_server": "https://mcp.example.com/v1/connect" }, "payment_methods": ["google_pay", "credit_card"], "security": { "type": "oauth2", "issuer": "https://auth.example.com" } }

Hosting Requirements

For the /.well-known/ucp endpoint to be valid and discoverable by global agents, it must meet rigorous hosting standards. Failure to comply with these requirements will result in the merchant being flagged as ‘ineligible’ within the Google AI Mode ecosystem.

Protocol and Path

The file must be served exclusively over HTTPS at the root domain. Subdomains are permitted only if they are registered as distinct merchant entities in Google Merchant Center. The absolute path is: https://{domain}/.well-known/ucp. Redirection (HTTP 301/302) should be avoided to minimize latency during the agent’s initial discovery phase.

HTTP Headers

To ensure proper parsing and cross-origin accessibility, the following headers are mandatory:

• Content-Type: application/json; charset=utf-8
• Access-Control-Allow-Origin: * (or a whitelist of trusted agent domains)
• Cache-Control: max-age=3600 (To ensure agents periodically refresh metadata without over-indexing)

High Availability

As this endpoint is the entry point for all agentic commerce, it should be hosted on a CDN or a highly available edge network. If a Gemini agent cannot reach this endpoint during a user’s purchase intent cycle, it will default to traditional search results rather than an autonomous checkout flow.

Validation and Security

Security is a critical pillar of the UCP specification. The discovery file exposes the architectural layout of your commerce stack, necessitating robust protection against malicious actors while maintaining accessibility for verified agents.

Verifying Agent Identity

While the /.well-known/ucp file itself is public, the endpoints it references must be protected. Merchants should implement Identity Linking to correlate a user’s Google account with their internal customer record. This is typically achieved via OAuth 2.0. When an agent like Gemini makes a request to a UCP endpoint, it will provide a bearer token obtained through the authorization flow defined in the discovery file.

Risk Signals and Integrity

The UCP specification allows for the transmission of Risk Signals. Within the JSON schema, developers can define a risk_provider. This allows the merchant to request that the agent provide telemetry data (within privacy bounds) to help mitigate fraud. Integration with Google’s Risk signals ensures that Native Checkout flows are as secure as traditional web-based checkouts.

Model Context Protocol (MCP) Integration

A novel aspect of the UCP discovery file is the inclusion of the mcp_server endpoint. The Model Context Protocol allows the merchant to provide the LLM with live context about product availability, complex pricing rules (such as California Prop 65 compliance or bulk discounts), and real-time shipping quotes. By advertising an MCP server in the well-known endpoint, the merchant enables the agent to act as a sophisticated personal shopper that understands the nuances of the inventory beyond what is available in a static Product Feed.

Integration with Google Ecosystem

The /.well-known/ucp endpoint acts as the glue between your backend and Google’s AI tools. By linking the merchant_id, Google can verify that the AI agent is interacting with a legitimate business already vetted through Google Merchant Center. This creates a circle of trust where Supplemental Feeds can be used to augment the data provided by the discovery endpoint, ensuring that the agent always has the most accurate information regarding eligibility signals and product attributes.

Conclusion

Implementing the /.well-known/ucp endpoint is not merely a technical requirement; it is a strategic move into the future of Agentic Commerce. By providing a structured, secure, and standardized discovery path, developers enable their commerce platforms to be navigated by the next generation of AI agents, moving beyond the browser and into the era of seamless, intent-driven transactions.