Endpoint Discovery

Endpoint discovery

Before anything runs, UCP Playground reads the store's UCP profile to learn which transports, capabilities and payment methods it declares. Choose any store to see what it publishes.

How it works

When you choose a store on Runs or in Inspect, the Playground fetches /.well-known/ucp from that host and parses the JSON profile. You see "Reading the store's UCP profile…" and then what it found. The profile says which UCP version the store runs, which transports it serves (MCP, REST, A2A, embedded) and where, what capabilities it declares, and which payment handlers it supports. The public Inspector reads the profile the same way when you enter a domain.

You only need the bare domain. The Playground builds the full URL, follows redirects and parses the response. Local hosts (localhost, *.local) keep their http:// scheme during discovery instead of being upgraded to HTTPS; see Localhost & Tunnels.

Tip

You don't need the full URL. Enter the domain, for example flowers.ucpsandbox.com or yourstore.ngrok.app, and the Playground fetches https://flowers.ucpsandbox.com/.well-known/ucp for you.

Profile formats

The current UCP releases are 2026-08-25 (latest) and 2026-04-08. Both list each service's transports as an array, one entry per transport, keyed by the service's reverse-domain name:

json
{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        { "transport": "mcp", "endpoint": "https://store.example.com/api/ucp/mcp", "version": "2026-08-25" },
        { "transport": "rest", "endpoint": "https://store.example.com/ucp/v1", "version": "2026-08-25" }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [{ "version": "2026-08-25" }]
    }
  }
}

Some stores still publish the older shape from early 2026 drafts, with one object per transport under a named service. The Playground reads both, plus a few platform-specific variations, without you choosing:

json
{
  "ucp": {
    "services": {
      "shopping": {
        "mcp": { "endpoint": "https://store.example.com/mcp" }
      }
    }
  }
}

What gets discovered

Before you start, the Info pane on Runs ("This run will use") and in Inspect ("The store") shows what the profile declares:

  • UCP profile: whether one was found, and the release it declares, against the releases a run supports (What a run supports)
  • Kind of store: Retail, Stays or Food, read from the capabilities it declares
  • Environment: Production, Pre-production (your own endpoints) or Test store
  • The store offers: the transports it declares, such as MCP, REST, A2A and Embedded. A store agent (A2A) gets its own row, read from its agent card; the store's checkout (Embedded) gets one too
  • Capabilities: the capabilities it declares
  • Account linking: whether the store offers UCP identity linking, and with which scopes

Once a run or an Inspect session starts, the discovery calls are recorded with it. The Discovery and negotiation tab shows how the agent found the store's UCP profile and what the two agreed to use, in three parts: Discovery (the profile read), Negotiation (the UCP version agreed, how many declared capabilities are active, and any extensions) and During the run (what passed between them while the agent shopped).

Transports

  • MCP: JSON-RPC tool calls. Runs and Inspect connect, list the tools and call them.
  • REST: the store's HTTP API. Runs and Inspect call it with the same tools, mapped to the store's REST routes.
  • A2A: the store agent. The profile's A2A entry points at its agent card; the Playground reads the card, checks it offers A2A 0.3 or 1.0 over JSON-RPC and lists UCP's extension, and sends checkout to the store agent. Search stays on MCP or REST. See A2A: the store's agent.
  • Embedded: the store's checkout (ECP). The profile entry has a schema and no endpoint. The agent builds the checkout over MCP or REST; when the store's checkout answer carries the embedded binding, the store's own checkout page opens beside the run. See Embedded: the store's checkout.

The store's website is a separate route: the tools a store's own web page registers through WebMCP. It is not a UCP transport and isn't read from the profile; see WebMCP: the store page.

HTTPS and Shopify endpoints

Endpoints declared with http:// are upgraded to https://, except on localhost and 127.0.0.1. When a Shopify profile lists both the UCP endpoint (/api/ucp/mcp) and the older storefront endpoint, the Playground connects to the UCP endpoint.

Your own endpoints

Testing a pre-production build that has no public profile yet? Add its endpoints under Settings › Stores & endpoints. A run there uses your endpoints directly and skips discovery, and is filed as Pre-production.

Stores without UCP

If a domain has no UCP profile at /.well-known/ucp, Runs says No UCP profile instead of showing an error. When you are signed in, Check the store's website opens the store in our browser and looks for tools there; if it finds some, the agent shops through the website. If not, it links to the store's readiness on UCP Checker. Inspect can't start on a store with no UCP profile.

Warning

Some stores require a linked buyer account before their tools accept certain requests. If discovery finds endpoints but calls come back asking for identity, link the account with the store first, or contact the merchant.

Something wrong on this page?