# The Agent Times UCP Gateway MCP

Endpoint: https://ucpg.ai/mcp

next_step: POST initialize, then tools/list, then resources/read ucp://gateway/skill-runtime-guide for lean SKILL.md runtime, ucp://gateway/profile-registration for first-time registration, or resources/read ucp://gateway/agent-guide / prompts/get ucp-shopping-flow.

## What this is

UCP Gateway is a hosted UCP profile registry plus provider-neutral Shopping MCP gateway. Agents can publish a public UCP profile, get an `agent_id`, search product catalogs, prepare buyer-confirmed carts, and create merchant-hosted checkout handoff links. The gateway is designed to avoid scraping, secret sharing, and payment-data handling.

## Supported transports

- **JSON-RPC POST**: primary transport. Send JSON-RPC 2.0 single requests or batches to `/mcp`.
- **SSE bootstrap**: GET `/mcp` with `Accept: text/event-stream` returns endpoint/session/method discovery events and may close. It is a bootstrap compatibility path, not a durable bidirectional SSE session.
- **Streamable HTTP compatibility**: `/mcp` supports GET, POST, OPTIONS, DELETE and `mcp-session-id` headers in stateless hosted mode. No server-side durable session is persisted; DELETE is a JSON cleanup/no-op.
- **POST fallbacks**: `/messages` and `/mcp/messages` accept the same stateless JSON-RPC POST messages for probing clients.

## Discovery sequence

1. POST `initialize` to get capabilities, supported methods, transports, and stateless session information.
2. POST `tools/list` to get authoritative tool names, input schemas, output schemas, and annotations.
3. POST `resources/list`, then `resources/read` with `ucp://gateway/skill-runtime-guide`, `ucp://gateway/profile-registration`, `ucp://gateway/agent-guide`, `ucp://gateway/shopping-flow`, `ucp://gateway/tool-reference`, or `ucp://gateway/safety-and-operator-handoff`.
4. POST `prompts/list`, then `prompts/get` with `ucp-skill-runtime-guide`, `ucp-shopping-flow`, `ucp-shopping-agent-guide`, `ucp-profile-registration`, or `ucp-operator-handoff`.
5. Use `tools/call` for executable work. Direct tool-name methods are accepted for simple callers, but `tools/call` is canonical.

SKILL.md-style agents should branch by `agent_id` availability and intent; they need not read every resource or prompt before acting.

## Supported JSON-RPC methods

- `initialize`
- `notifications/initialized`
- `ping`
- `tools/list`
- `tools/call`
- `resources/list`
- `resources/read`
- `resources/templates/list`
- `prompts/list`
- `prompts/get`

## Tools at a glance

Read-only/discovery tools:
- `get_ucp_profile` — Fetch one registered UCP profile by namespace and agent_id.
- `shopping_product_search` — Search the product catalog through The Agent Times UCP Gateway.
- `shopping_product_get` — Get product details by provider product or variant ID.
- `shopping_cart_get` — Refresh a merchant cart state.
- `shopping_checkout_get` — Refresh merchant checkout state.

State-changing tools requiring buyer/operator care:
- `register_ucp_profile` — Register a public hosted UCP agent profile and receive agent_id/profile_url. Default path: send agent_name plus public_key_jwk and the gateway builds the canonical UCP profile with default Shopping capabilities. Re-registering the same public_key_jwk in the same namespace is idempotent and returns the existing agent_id. Do not build a capability map for normal registration. Create local ./.ucpgateway/ files; keep private_key.jwk local and save returned agent_id/profile_url/profile_json to ./.ucpgateway/agent.json.
- `shopping_cart_create` — Create a merchant cart after the buyer/operator confirms selected variants.
- `shopping_cart_update` — Replace a merchant cart with the full desired cart state.
- `shopping_cart_cancel` — Cancel a merchant cart using an idempotency key.
- `shopping_checkout_create` — Create a merchant checkout handoff URL after operator confirmation. Does not accept payment credentials. Buyer phone should be E.164 and country must be ISO-2.
- `shopping_checkout_update` — Update checkout with a full desired checkout object; use sparingly after checkout exists. Buyer phone should be E.164 and country must be ISO-2.
- `shopping_checkout_cancel` — Cancel an active merchant checkout using an idempotency key.

Full request/response schemas are returned by `tools/list`; this guide intentionally does not duplicate large schemas.

## Profile registration quick start

First-time agents should read `ucp://gateway/profile-registration` for the complete self-serve guide. In short:

1. Create `./.ucpgateway/` in the agent working directory if you need persistent local state.
2. Generate an ECDSA P-256 signing key pair. Save the private JWK as `./.ucpgateway/private_key.jwk` with restrictive permissions such as `0600`; never log or upload it.
3. Save the public JWK as `./.ucpgateway/public_key.jwk`.
4. Call `tools/call` with `name: "register_ucp_profile"` and arguments `agent_name`, `public_key_jwk`, optional `namespace`, optional `description`, optional public `metadata`, optional `skill_name`, and optional `skill_version`.
5. The gateway builds the canonical UCP profile, default Shopping capabilities, `payment_handlers: {}`, public `signing_keys`, and metadata. Normal agents do not build or send a capability map.
6. Save returned `agent_id`, `namespace`, `profile_url`, `registry_url`, `gateway_mcp_url`, `created`, `existing_profile`, `message`, local `saved_at`, and generated `profile_json` to `./.ucpgateway/agent.json`.

Re-registering the same public key in the same namespace is idempotent: `existing_profile: true`, `created: false`, same `agent_id`, and the hosted profile is not modified. The registration response does not include a profile creation timestamp.

Advanced legacy callers may send `profile_json` instead of `public_key_jwk`, but never both. Legacy capability keys must be exact:

- `dev.ucp.shopping.catalog.search`
- `dev.ucp.shopping.catalog.lookup`
- `dev.ucp.shopping.catalog`
- `dev.ucp.shopping.cart`
- `dev.ucp.shopping.checkout`

`shopping` is not valid shorthand. `dev.ucp.shopping` is also invalid shorthand. The default `public_key_jwk` path avoids this problem because the caller does not send capabilities.

## Shopping sequence

1. Register or load an active `agent_id` with `register_ucp_profile` / `get_ucp_profile`.
2. Search with `shopping_product_search`.
3. Use `shopping_product_get` when variant, merchant, or availability details are needed.
4. Show provider-returned options, prices, availability, merchant domain, URLs, variant IDs/options, messages, and warnings.
5. Ask the buyer/operator to choose exact variant(s) and quantity.
6. Create or update cart only after confirmation.
7. Show returned cart totals/messages/warnings.
8. Ask final confirmation before checkout; only then set `operator_confirmed: true`.
9. Create checkout with `shopping_checkout_create` and hand off `continue_url`. Payment happens on the merchant site only.

## Safety/operator requirements

- Do not scrape merchant sites or invent provider data.
- Do not send payment credentials, card numbers, CVV, bank/wallet credentials, payment tokens, one-time payment codes, passwords, or payment methods.
- Do not invent buyer PII. Ask the buyer/operator or omit optional fields.
- Do not say an order is complete, paid, or placed. The gateway returns merchant checkout handoff links.
- Treat `requires_escalation` and `REQUIRES_ESCALATION_*` as merchant-hosted handoff signals, not completion.

## How to interpret next_step

Every JSON-RPC response or error includes `next_step` guidance. For tool calls, read `result.structuredContent.next_step` and/or `result.next_step`. It recommends methods/tools, gives non-binding argument hints, and lists safety warnings. Argument hints are never buyer authorization for cart, checkout, payment, or retries.