Was ein UCP-Manifest ist — und wann es falsch ist, eines zu veröffentlichen

Ein UCP-Manifest ist eine JSON-Datei unter /.well-known/ucp, die KI-Shopping-Agenten mitteilt, was Ihr Shop kann und wo sie ihn aufrufen können. Es ist keine Marketing-Datei und keine Alibi-Geste — es deklariert echte API-Endpunkte und die öffentlichen Schlüssel, mit denen Ihre signierten Nachrichten geprüft werden. Dieser Leitfaden erklärt, was in die Datei gehört, was nicht, wie Sie sie aus Shopify heraus ausliefern und wann es falsch ist, überhaupt eine zu veröffentlichen.

Was UCP ist

Das Universal Commerce Protocol ist ein offener Standard, den Google unter Apache 2.0 veröffentlicht hat, für maschinenlesbare Händler-Discovery. Während llms.txt und agents.md ein Unternehmen in zitierbarer Prosa beschreiben, beschreibt UCP eine Schnittstelle: die Dienste, die ein Agent aufrufen kann, um zu stöbern, zu bestellen und eine Bestellung zu verfolgen — ohne Menschen dazwischen.

Der Einstiegspunkt ist eine einzige Well-Known-URL. Ein Agent ruft https://ihr-shop.example/.well-known/ucp ab, liest das JSON und erfährt, welche Protokollversion Sie sprechen, welche Endpunkte er ansprechen soll und wie er prüft, ob Nachrichten wirklich von Ihnen stammen.

Was die Datei enthalten muss

Zwei Pflichtfelder auf oberster Ebene: ucp und signing_keys.

• ucp.version — die Protokollversion als Datum: "2026-04-08". UCP-Versionen sind Daten, kein SemVer.
• ucp.services — eine Zuordnung von Dienstkennungen wie dev.ucp.shopping zu ihren Transport-Bindings: Version, Spec-URL, Transport (rest, mcp, a2a oder embedded), Schema-URL und der endpoint, den ein Agent aufrufen soll.
• ucp.capabilities — eine Zuordnung der Funktionen innerhalb dieser Dienste, etwa dev.ucp.shopping.checkout, jeweils mit eigener Version und eigenem Schema. Erweiterungen benennen ihre übergeordnete Capability.
• signing_keys — öffentliche Schlüssel im JWK-Format, mit denen Webhooks und authentifizierte Nachrichten geprüft werden, die Sie signieren (RFC 9421, HTTP Message Signatures). Die Spezifikation führt das Feld auf oberster Ebene, Shopifys eigene Manifeste lassen es jedoch ganz weg — sein Fehlen ist also normal und kein Mangel, den Sie beheben müssten.

ucp.payment_handlers ist optional. Wenn Sie mehrere Protokollversionen unterstützen, verweist eine supported_versions-Zuordnung auf versionsspezifische Profil-URLs.

Ein minimal gültiges Manifest

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/overview",
        "transport": "rest",
        "endpoint": "https://business.example.com/ucp/v1",
        "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
      }]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/checkout",
        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
      }]
    }
  },
  "signing_keys": [{
    "kid": "business_2026",
    "kty": "EC", "crv": "P-256", "use": "sig", "alg": "ES256",
    "x": "…", "y": "…"
  }]
}

Beachten Sie, was dieser endpoint bedeutet: eine echte URL, die ein Agent aufrufen wird. Ein Manifest ist ein Versprechen über Infrastruktur, die es geben muss.

Auf Shopify haben Sie bereits eines

Diesen Punkt stellen die meisten Anleitungen falsch dar. Shopify hat UCP gemeinsam mit Google entwickelt und aktiviert es standardmäßig für Shops — Ihre Storefront liefert also bereits ein Manifest unter /.well-known/ucp aus, ohne dass Sie etwas konfigurieren. Prüfen Sie Ihres:

curl -sSL https://ihr-shop.example/.well-known/ucp | jq .

Ein echtes Shopify-Manifest deklariert einen mcp-Transport auf https://ihr-shop.myshopify.com/api/ucp/mcp, eine supported_versions-Zuordnung, Capabilities wie checkout, cart, fulfillment, discount, order sowie Katalogsuche und -abfrage, dazu Payment-Handler wie Google Pay und Shop Pay. Nichts davon schreiben Sie selbst — und Sie sollten es auch nicht ersetzen wollen.

Auf Shopify besteht die Arbeit also im Prüfen, nicht im Verfassen: Stellen Sie sicher, dass die Datei auf Ihrer Live-Domain auflöst, dass sie überlebt, was auch immer vor Ihrem Shop sitzt, und dass nichts, was Sie ergänzt haben, sie blockiert. Selbst schreiben müssen Sie eines nur bei Headless-Setups und eigenen Frontends, wo Sie den Webserver kontrollieren und die Plattform den Pfad nicht für Sie ausliefert. Dann führen üblicherweise eine URL-Weiterleitung oder ein App-Proxy zum Ziel — und alles oben Gesagte über das Deklarieren nur solcher Endpunkte, die auch antworten, gilt weiterhin.

Wann man keines veröffentlichen sollte

Ein leeres oder erfundenes Manifest ist schlechter als gar keines. Führt services einen Endpunkt auf, der nicht antwortet, findet ein Agent Sie, ruft ihn auf und scheitert — ein schlechteres Ergebnis als ein sauberer 404, der ihm sofort sagt, dass er auf Ihre Seiten zurückfallen soll.

Das gilt auch für Sites, die gar keine Storefront sind. Unsere eigene Marketing-Site liefert unter /.well-known/ucp bewusst einen 404: Sie verkauft nichts, es gibt also keinen Endpunkt zu deklarieren, und die Spezifikation kennt keine Möglichkeit zu sagen „Ich bin kein Händler". Ein Stub, der nur existiert, damit ein Prüfer grün wird, ist ein Häkchen, keine Bereitschaft.

So prüfen Sie Ihres

Drei Dinge, in dieser Reihenfolge: Die Datei liefert einem nicht authentifizierten Client 200, ihr Inhalt parst als JSON, und jede URL in services löst auf. Sichtas Pillar-A-Prüfungen decken die ersten beiden als Prüfung A1 ab und melden das Ergebnis getrennt von Ihren übrigen Befunden — ein fehlendes Manifest ist damit ein konkreter Punkt und keine Zahl, die man deuten muss.

Die Spezifikation bewegt sich noch — Versionen sind Daten, das Schema entwickelt sich — behandeln Sie das Manifest also als etwas, das Sie neu erzeugen, nicht als etwas, das Sie einmal schreiben und vergessen.

Kurz gefasst

Veröffentlichen Sie ein UCP-Manifest, wenn Sie einen Commerce-Endpunkt haben, den ein Agent tatsächlich aufrufen kann. Liefern Sie es unter /.well-known/ucp als nicht authentifiziertes JSON aus, deklarieren Sie einen echten endpoint und echte signing_keys, und prüfen Sie es mit einem einfachen HTTP-Client statt im Browser. Fehlt Ihnen diese Infrastruktur noch, ist ein 404 die ehrliche Antwort — und llms.txt plus agents.md sind das, was sich heute auszahlt.