What /.well-known/ucp is, and how to serve it correctly

What the file is

An agent that wants to transact with a business does not read your homepage. It fetches a JSON document from a fixed path on your domain, reads which protocol version you speak and which services and capabilities you expose, intersects that with its own, and negotiates from there. That document is the business profile, and the path is fixed.

Two things follow from that paragraph and are worth stating before anything else. The profile carries protocol metadata and nothing else: there is no field for your company name, your description or a contact address, so a profile is not an “AI business card” however often it is described as one. And the smallest structurally valid document is almost empty:

{
  "ucp": {
    "version": "2026-08-25",
    "services": {},
    "payment_handlers": {}
  }
}

That document is conformant and worthless. It tells an agent you speak the protocol and expose nothing it can act on. Publishing it to make a checker go green is the one mistake this whole page is trying to prevent.

The five rules for serving it

Conformance is not only about the JSON. The specification puts normative requirements on the response itself, under Profile Requirements → Hosting.

All five are visible in the response headers, so you can check them yourself in one command:

curl -sS -D - -o /dev/null https://yourstore.com/.well-known/ucp

# What you are looking for, in order:
#   HTTP/2 200                          <- not 301, 302, 307 or 308
#   content-type: application/json      <- not text/html
#   cache-control: public, max-age=300  <- public, and at least 60
#   etag: "..."                         <- or last-modified

What goes inside the profile

services says where an agent can reach you and over which transport — rest, mcp, a2a or embedded. Each entry needs a version, a spec URL and a transport, and REST, MCP and embedded entries also need a schema. capabilities is how an agent matches your store to a shopping intent; the intersection of your capabilities and the agent's is what gets negotiated. payment_handlers declares what your checkout accepts.

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-08-25",
          "spec": "https://ucp.dev/2026-08-25/specification/overview/",
          "transport": "rest",
          "endpoint": "https://yourstore.com/ucp/shopping",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-25",
          "spec": "https://ucp.dev/2026-08-25/capabilities/checkout/",
          "schema": "https://ucp.dev/2026-08-25/capabilities/checkout/schema.json"
        }
      ]
    },
    "payment_handlers": {},
    "supported_versions": {
      "2026-04-08": "https://yourstore.com/.well-known/ucp/2026-04-08"
    }
  },
  "keys": []
}

Serving it, per platform

The hard part is rarely producing the JSON. It is getting your platform to answer at that exact path, with a 200 and your own headers. Most hosted platforms reserve the path, rewrite it, or hand you only a redirect rule.

Whatever the platform, the mechanism is the same: answer at the requested URL. These three do that.

# nginx: serve the file at the path itself. A rewrite or proxy_pass keeps
# the 200; "return 301" would fail discovery outright.
location = /.well-known/ucp {
    default_type application/json;
    add_header Cache-Control "public, max-age=300" always;
    alias /var/www/ucp/profile.json;
}

# Apache: Alias maps the path without issuing a redirect.
Alias "/.well-known/ucp" "/var/www/ucp/profile.json"

<Files "profile.json">
    ForceType application/json
    Header set Cache-Control "public, max-age=300"
</Files>

// Cloudflare Worker, for a platform that will not let you add a file.
// This answers at the requested URL, so it is not a redirect.
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname === "/.well-known/ucp") {
      return new Response(JSON.stringify(PROFILE), {
        headers: {
          "content-type": "application/json",
          "cache-control": "public, max-age=300",
        },
      });
    }
    return fetch(request);
  },
};

Versions, and why they go stale quietly

UCP versions are dates, and matching is exact. The current release is 2026-08-25. An agent on a release your profile does not declare will not negotiate with you, and nothing anywhere logs an error you would see — the store simply stops being reachable to that agent.

So a profile is not a file you publish once. It is a file with a maintenance schedule attached, and the cost of forgetting it is silent.