UCP profile setup
Your UCP profile is a JSON document at /.well-known/ucp on your domain. The UCP specification calls it the business profile. It tells agents where your endpoints are, which transports and capabilities you support, and which payment handlers you accept.
Where it lives
When an agent or UCP Playground connects to your store, it first fetches https://yourdomain.com/.well-known/ucp. This is the discovery path the UCP specification defines. If the file is missing or returns an error, agents cannot find your endpoints.
To see a working profile, fetch one of our test stores, for example flowers.ucpsandbox.com/.well-known/ucp (Retail). The examples on this page follow its shape.
Profile formats
UCP Playground reads the current format and the older ones. Use the latest specification for new work.
2026-08-25 (latest)
The document has a ucp root member. Services are keyed by reverse-domain name (dev.ucp.shopping), each a list of transport entries. Capabilities use registry names such as dev.ucp.shopping.catalog.search. Each service and capability entry carries its version, spec and schema URLs. An extension, such as fulfillment, lists the capabilities it builds on in extends. Your public signing keys sit in a root-level keys array, which replaces signing_keys. See the full specification.
{
"ucp": {
"version": "2026-08-25",
"supported_versions": {
"2026-04-08": "https://yourstore.com/.well-known/ucp/2026-04-08"
},
"services": {
"dev.ucp.shopping": [
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/overview",
"transport": "rest",
"schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json",
"endpoint": "https://yourstore.com/ucp"
},
{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/overview",
"transport": "mcp",
"schema": "https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json",
"endpoint": "https://yourstore.com/mcp"
}
]
},
"capabilities": {
"dev.ucp.shopping.catalog.search": [{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/search",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json"
}],
"dev.ucp.shopping.checkout": [{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
}],
"dev.ucp.shopping.fulfillment": [{
"version": "2026-08-25",
"spec": "https://ucp.dev/2026-08-25/specification/shopping/extensions/fulfillment",
"schema": "https://ucp.dev/2026-08-25/schemas/shopping/fulfillment.json",
"extends": ["dev.ucp.shopping.checkout"]
}]
},
"payment_handlers": {
"com.google.pay": [{ "id": "gpay", "version": "2026-08-25", "config": { } }]
}
},
"keys": [
{ "kid": "store-key-1", "kty": "OKP", "crv": "Ed25519", "x": "...", "use": "sig", "alg": "EdDSA" }
]
}supported_versions is optional. It maps each older version you still serve to the URL of that version's profile, so a platform on an earlier release can still connect. A platform whose version you neither run nor list may be refused.
Our test stores also publish signing_keys with the same keys, for verifiers still on 2026-04-08, and a dev.ucp.common service for location search and lookup.
2026-04-08
The same ucp root and dev.ucp.shopping service key, usually with lighter entries. Still read in full:
{
"ucp": {
"version": "2026-04-08",
"services": {
"dev.ucp.shopping": [
{
"transport": "mcp",
"endpoint": "https://yourstore.com/mcp",
"version": "2026-04-08"
}
]
},
"capabilities": {
"dev.ucp.shopping.catalog.search": [{ "version": "2026-04-08" }],
"dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }]
}
}
}2026-01-23
Uses an array of transport objects under a plain shopping key:
{
"services": {
"shopping": [
{
"transport": "mcp",
"endpoint": "https://yourstore.com/mcp"
}
]
}
}2026-01-11 (legacy)
The original format nests the transport under a named key. Still read, but don't use it for new work:
{
"services": {
"shopping": {
"mcp": {
"endpoint": "https://yourstore.com/mcp"
}
}
}
}Required and optional fields
At a minimum, your profile needs services with at least one transport endpoint. Without it, agents have nothing to connect to.
- version (recommended) — the UCP version your store runs, for example
"2026-08-25". - supported_versions (optional) — older versions you also serve, each mapped to its profile URL.
- services (required) — service names mapped to their transport entries. The shopping service key is
dev.ucp.shopping; older formats useshopping. - transport (required from 2026-01-23) —
"mcp","rest","a2a"or"embedded"(the store's checkout, Embedded Checkout Protocol). The Playground uses all four: tools over MCP and REST, checkout to the store agent over A2A, and the store's own checkout page beside the run for Embedded. - endpoint (required for MCP, REST and A2A) — the full URL of that transport's endpoint. For A2A it is the agent card's URL (
/.well-known/agent-card.json). An"embedded"entry has aschemaand no endpoint: each checkout answer says whether it can open embedded. - capabilities (optional) — what your store supports (search, cart, checkout and so on), with versions. The Playground compares them with its own and shows the result on a run's Discovery and negotiation tab.
- payment_handlers (optional) — the payment handlers your store accepts, keyed by handler name.
- agent_guide (optional) — guidance for agents on how to use your store: an
abouttext,rulesandbuyer_options. The public Inspector shows it when present. - keys (optional, root level) — your public signing keys as a JWK Set, used to verify the webhooks you send. See Order webhooks.
Payment handlers
Declare the payment handlers you accept in payment_handlers, so agents know which options to offer. Each key is a handler name. Its value is a list of entries with an id, a version, the handler's spec, the instruments it takes and its own config. This is the block our test stores publish; a real store lists its real handlers, such as com.google.pay:
"payment_handlers": {
"dev.mock.payment_handler": [
{
"id": "mock_payment_handler",
"version": "2026-08-25",
"spec": "https://mock.dev/ucp/payment-handler",
"available_instruments": [{ "type": "card" }],
"config": {}
}
]
} Serve your profile with Content-Type: application/json and Access-Control-Allow-Origin: *. UCP Playground fetches it from its own servers, but browser-based agents and tools fetch it cross-origin.
The profile must be public, with no sign-in, API key or IP restriction in front of it. Agents read it before they have any credentials.
Something wrong on this page?