UCP Manifest Setup

The UCP manifest is a JSON document hosted at /.well-known/ucp on your domain. It tells AI agents where your endpoints are, which transports and capabilities you support, and what payment methods you accept.

Where It Lives

When an agent or UCP Playground connects to your store, the first thing it does is fetch https://yourdomain.com/.well-known/ucp. This is the standard discovery path defined by the UCP specification. If this file is missing or returns an error, agents cannot discover your store's capabilities.

Manifest Formats

UCP Playground reads the current format and the older ones. The latest specification is recommended for new implementations.

v2026-08-25 Format (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 like dev.ucp.shopping.catalog.search. In this version each service and capability entry carries its version, spec and schema URLs, and your public signing keys sit in a root-level keys array (it 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": "mcp",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json",
          "endpoint": "https://yourstore.com/mcp"
        },
        {
          "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"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{
        "version": "2026-08-25",
        "spec": "https://ucp.dev/2026-08-25/specification/shopping/catalog/",
        "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"
      }]
    },
    "payment_handlers": {
      "com.google.pay": [{ "id": "gpay", "version": "2026-08-25", "config": { } }]
    }
  },
  "keys": [
    { "kid": "store-key-1", "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "use": "sig", "alg": "ES256" }
  ]
}

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 don't run and don't list may be refused.

v2026-04-08 Format

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" }]
    }
  }
}

v2026-01-23 Format

Uses an array of transport objects under a plain shopping key:

{
  "services": {
    "shopping": [
      {
        "transport": "mcp",
        "endpoint": "https://yourstore.com/mcp"
      }
    ]
  }
}

v2026-01-11 Format (Legacy)

The original format nests the transport configuration under a named key. Still read, but not recommended for new implementations:

{
  "services": {
    "shopping": {
      "mcp": {
        "endpoint": "https://yourstore.com/mcp"
      }
    }
  }
}

Required and Optional Fields

At a minimum, your manifest must include services with at least one transport endpoint. Without this, agents have nothing to connect to.

• version (recommended) — The UCP version your store runs, e.g. "2026-08-25".
• supported_versions (optional) — Older versions you also serve, each mapped to its profile URL.
• services (required) — A map of service names to their transport entries. The standard e-commerce service key is dev.ucp.shopping; older formats use shopping.
• transport (required in v2026-01-23+) — "mcp", "rest", "a2a", or "embedded" (the Embedded Checkout handoff). The Playground connects over MCP and REST; an A2A endpoint is shown as declared, and an embedded entry is used at the checkout step.
• endpoint (required) — The full URL of that transport's endpoint.
• capabilities (optional) — Structured capability declarations with versions. Tells agents what your store supports (search, cart, checkout, etc.). The Playground compares them with its own and shows the result as the negotiation readout.
• payment_handlers (optional) — The payment handlers your store accepts, keyed by handler name.
• agent_guide (optional) — Guidance for AI agents on how to use your store (an about text, rules and buyer_options). The Inspector shows it when present.
• keys (optional, root level) — Your public signing keys as a JWK Set, used to verify webhooks you send. See Agent Identity & Webhooks.

Advertising Payment Methods

If your store accepts specific payment methods, declare them in payment_handlers so agents know what payment options to present. Each key is a handler name; its value is a list of handler entries with an id, a version and the handler's own config:

"payment_handlers": {
  "com.google.pay": [
    { "id": "gpay", "version": "2026-08-25", "config": { } }
  ]
}