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, what transport layers 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 supports three manifest formats. The latest specification is recommended for new implementations.

v2026-04-08 Format (Latest)

The current version wraps the document in a ucp root member, keys services by reverse-domain name (dev.ucp.shopping), and declares capabilities using registry names like dev.ucp.shopping.catalog.search. See the full specification.

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "transport": "mcp",
          "endpoint": "https://yourstore.com/mcp",
          "version": "2026-04-08"
        },
        {
          "transport": "rest",
          "endpoint": "https://yourstore.com/ucp",
          "schema": "https://yourstore.com/ucp/openapi.json",
          "version": "2026-04-08"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.catalog.lookup": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.cart": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }]
    }
  }
}

v2026-01-23 Format

Uses an array of transport objects, making it straightforward to advertise multiple transports for the same service:

{
  "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 supported 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 the services object with at least one transport endpoint. Without this, agents have nothing to connect to.

• version (recommended) — The manifest format version string, e.g. "2026-04-08".
• services (required) — A map of service names to their transport configurations. In v2026-04-08 the standard e-commerce service key is dev.ucp.shopping; older formats use shopping.
• transport (required in v2026-01-23+) — The protocol identifier: "mcp", "a2a", or "rest".
• endpoint (required) — The full URL of your MCP, A2A, or REST endpoint.
• capabilities (optional) — Structured capability declarations with versions. Tells agents what your store supports (search, cart, checkout, etc.).
• agent_guide (optional, v2026-04-08+) — Free-text instructions for AI agents on how to use your store's tools.
• payment_handlers (optional) — An array of payment method identifiers your store accepts.

Advertising Payment Methods

If your store accepts specific digital payment methods, list them in payment_handlers so agents know what payment options to present to users:

{
  "payment_handlers": [
    "com.google.pay",
    "com.apple.pay"
  ]
}