The Store’s Front Door for AI

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. By serving a standardized JSON document at a predictable location, you transform your static web store into a machine-readable commerce node. 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.

JSON Schema Breakdown

The discovery document must be served as application/json and contain specific top-level keys that define your store’s identity and its interface. The core of the document is the merchant_id, which should align with your Google Merchant Center ID to ensure seamless data synchronization between your product feeds and the agentic layer.

The Capabilities Object

The capabilities object is where you define the level of support your store provides. Currently, UCP distinguishes between two primary checkout paths: Native Checkout and Embedded Checkout. Native Checkout (native_checkout: true) indicates that your store can process a transaction entirely via the REST API, typically using a secure payment credential like Google Pay. This is the gold standard for agentic commerce, as it allows the agent to complete the purchase without the user ever leaving the chat interface. Embedded Checkout, conversely, signals that while the agent can build the cart, the final payment must occur within a web-view or a redirected browser session.

The Endpoints Map

The endpoints section provides the base URLs for the various UCP-compliant REST API services. These typically include:

• products_url: For real-time inventory and pricing checks.
• cart_url: For managing the session-based shopping bag.
• checkout_url: The entry point for the payment and shipping selection process.
• webhook_url: Where the UCP bridge should send notifications regarding order status updates.

By defining these clearly, you allow the agent to construct requests dynamically. For instance, if an agent needs to calculate shipping for a user in a specific zip code, it uses the checkout_url defined in your discovery document to POST a shipping estimation request.

CORS and Security Headers

Because the UCP discovery endpoint is often accessed by client-side agents or cross-domain services like Google AI Mode, your server must be configured with robust Cross-Origin Resource Sharing (CORS) policies. Without the correct headers, an MCP client running in a browser environment will be blocked from reading your manifest. Your server should return an Access-Control-Allow-Origin: * header for the /.well-known/ucp path, or at a minimum, whitelist the specific domains used by the UCP bridge.

Security is equally paramount. The discovery endpoint must be served over HTTPS. Any manifest served over insecure HTTP will be ignored by the protocol to prevent man-in-the-middle attacks where a malicious actor could redirect an agent to a fraudulent checkout URL. Furthermore, while the discovery document itself is public, the REST API endpoints it points to should be protected by OAuth 2.0. The manifest can optionally include an auth_config key that specifies the token endpoint and supported scopes, allowing the agent to request the necessary permissions from the user before initiating a transaction.

Validation and Testing Tools

Once you have deployed your JSON manifest, it is vital to validate it against the UCP core schema. Errors in the discovery document are the leading cause of integration failures in the Google ecosystem. Developers can use the UCP Validator tool, which simulates a Gemini agent’s discovery process. It checks for schema compliance, ensures that all mandatory REST API endpoints are reachable, and verifies that your CORS headers are correctly implemented.

Integrating with Model Context Protocol (MCP)

For developers building more complex agentic experiences, integrating the discovery endpoint with an MCP server allows for even deeper functionality. MCP acts as the translation layer between the Large Language Model and your backend. By pointing your MCP server to your /.well-known/ucp file, you can automatically generate the tool definitions that Gemini uses to call your store’s functions. This synergy between UCP for data structure and MCP for execution represents the future of high-conversion, low-friction commerce.

Finally, remember to sync your implementation with your Google Merchant Center account. By adding your discovery URL to your Merchant Center profile, you signal to Google’s ranking and eligibility engines that your store is ‘Agent Ready.’ This can improve your visibility in Gemini-driven shopping results, as the AI can prioritize stores where it has a high degree of confidence in completing a Native Checkout transaction.