What Is the UCP-Agent Header and Platform Advertisement in Universal Commerce Protocol?

The UCP-Agent header is an RFC 8941 dictionary that advertises a client's profile URI on every request, enabling verifiable identity authentication, dynamic capability negotiation, and mandatory platform advertisement across HTTP and MCP transports.

In the Universal Commerce Protocol (UCP) ecosystem, agents and platforms must establish cryptographic trust and negotiate supported features before processing commerce transactions. The UCP-Agent header serves as the cornerstone of this interaction, containing a pointer to the sender's public profile which hosts signing keys, capabilities, and version metadata. According to the source implementation in Universal-Commerce-Protocol/ucp, this mechanism is defined in source/services/shopping/rest.openapi.json and specified in the protocol documentation.

Core Functions of the UCP-Agent Header

The UCP-Agent header performs three critical roles in the UCP security and extensibility model: identity verification, capability discovery, and platform advertisement.

Identity and Authentication

The header value follows the RFC 8941 Structured Header format as a dictionary entry: profile="https://…/.well-known/ucp". When a merchant or counterparty receives a request containing this header, they fetch the advertised profile URI to retrieve the agent's public signing key. The receiver then verifies the request's cryptographic signature against this key to ensure the caller controls the claimed identity. As implemented in docs/specification/signatures.md, this binding prevents identity spoofing by requiring the sender to prove possession of the private key corresponding to the advertised public key.

Capability Negotiation

By exposing its profile, an agent announces which commerce capabilities it supports—such as specific payment methods, fulfillment options, or inventory management features. The receiving business computes the intersection of its own capabilities with those advertised by the platform, ensuring both sides operate with a mutually understood feature set before executing transactions. This dynamic discovery eliminates hardcoded integrations and allows for protocol extensions without breaking existing implementations.

Platform Advertisement Requirements

UCP mandates that every request sent by a platform (such as a shopping-service provider) must carry identification information, enabling the receiving merchant to fetch, cache, and validate the platform's profile according to cache-control rules.

HTTP Transport Implementation

For RESTful HTTP interactions, the platform includes the UCP-Agent header directly in the request headers. The OpenAPI specification in source/services/shopping/rest.openapi.json (lines 877-885) defines this as a required header containing the profile URI.

POST /checkout HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"

{
  "line_items": [{ "id": "prod_123", "quantity": 2 }]
}

This header tells the merchant exactly which agent is calling and where to retrieve its cryptographic profile for signature verification.

MCP (JSON-RPC) Transport Implementation

When using the Model Context Protocol transport, the same advertisement information appears within the JSON-RPC payload structure rather than HTTP headers. As specified in docs/specification/overview.md (lines 562-571), the platform places the profile URI inside a meta.ucp-agent object.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://agent.example/profiles/shopping-agent.json"
        }
      },
      "checkout": { "line_items": [...] }
    }
  },
  "id": 1
}

The meta.ucp-agent.profile field mirrors the HTTP header functionality, ensuring consistent identity advertisement regardless of transport mechanism.

Security Implementation and Signed Requests

The UCP-Agent header plays a crucial role in request integrity. When signing requests, the header must be included in the signature payload to create cryptographic proof that the sender indeed controls the advertised profile.

As shown in docs/specification/signatures.md (lines 260-267), the header appears in the Signature-Input field along with other critical components:

POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig1=("@method" "@authority" "@path" "ucp-agent" "idempotency-key" "content-digest" "content-type");keyid="platform-2026"
Signature: sig1=:MEUCIQDTxNq8h7LGHpvVZQp1iHkFp9+3N8Mxk2zH1wK4YuVN8w...:

{"checkout":{"line_items":[{"id":"prod_123","quantity":2}]}}

By signing the ucp-agent value, the platform proves non-repudiation—it cannot later deny sending the request, and the merchant can verify that the profile URI was not tampered with in transit.

Summary

• The UCP-Agent header is an RFC 8941 dictionary containing a profile URI that points to the agent's public identity document.
• Identity verification works by fetching the advertised profile, caching it according to cache-control rules, and verifying request signatures against the public key contained within.
• Capability negotiation allows automatic discovery of supported payment methods and fulfillment options by comparing advertised profiles between parties.
• Platform advertisement is mandatory on every request, implemented via the UCP-Agent header in HTTP or the meta.ucp-agent object in MCP transports.
• Cryptographic binding requires including the UCP-Agent header in signed components to prevent tampering and prove sender authenticity.

Frequently Asked Questions

What format does the UCP-Agent header use according to the specification?

The header uses the RFC 8941 Structured Headers format as a dictionary string containing a single profile key. The value is a URI string pointing to the agent's .well-known/ucp endpoint, formatted as profile="https://example.com/.well-known/ucp". This format is explicitly defined in source/services/shopping/rest.openapi.json to ensure consistent parsing across implementations.

How does platform advertisement differ between HTTP and MCP transports?

While HTTP requests carry the advertisement in the UCP-Agent header, MCP (JSON-RPC) requests embed the same information inside the meta.ucp-agent object within the request parameters. Both mechanisms contain identical profile URI information and serve the same purpose of identity and capability advertisement, as documented in docs/specification/overview.md.

Why must the UCP-Agent header be included in request signatures?

Including the header in the Signature-Input creates cryptographic proof that the sender controls the advertised profile URI. This prevents man-in-the-middle attacks where an attacker might substitute their own profile URL, and it ensures non-repudiation—the sender cannot deny initiating the request because the signature binds their identity to the specific HTTP components.

Where can I find the formal definition of the UCP-Agent header in the source code?

The formal OpenAPI definition resides in source/services/shopping/rest.openapi.json at lines 877-885, which specifies the header as required and describes its RFC 8941 format. Additional implementation details and examples appear in docs/specification/signatures.md (lines 260-267) and docs/specification/overview.md (lines 562-571).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}