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

> Understand the UCP-Agent header's role in Universal Commerce Protocol for verifiable identity, capability negotiation, and platform advertisement across HTTP and MCP. Learn its purpose.

- Repository: [Universal Commerce Protocol (UCP)/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
- Tags: getting-started
- Published: 2026-04-26

---

**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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/services/shopping/rest.openapi.json) (lines 877-885) defines this as a required header containing the profile URI.

```http
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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md) (lines 562-571), the platform places the profile URI inside a `meta.ucp-agent` object.

```json
{
  "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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/signatures.md) (lines 260-267), the header appears in the `Signature-Input` field along with other critical components:

```http
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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/signatures.md) (lines 260-267) and [`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md) (lines 562-571).