MCP Endpoint Configuration

Your MCP endpoint is the core of your UCP integration. It receives JSON-RPC 2.0 requests over HTTP POST and returns structured responses that AI agents use to browse, cart, and checkout.

Protocol Basics

MCP (Model Context Protocol) uses JSON-RPC 2.0 as its wire format. Every request is an HTTP POST to your endpoint with a JSON body containing a method name, parameters, and a request ID. Your endpoint must respond with the corresponding JSON-RPC result or error.

All requests use Content-Type: application/json and your responses should do the same.

Required Methods

Your endpoint must handle at least three methods. A fourth is optional but useful for certain agent workflows:

• initialize — The protocol handshake. The client sends its protocolVersion, clientInfo, and capabilities; respond with your own protocolVersion, serverInfo, and capabilities. If you return an Mcp-Session-Id response header here, clients echo it on every subsequent request in the session (streamable-HTTP session continuity).
• tools/list — Returns the full set of tools your store supports. Each tool includes a name, description, and a JSON Schema defining its input parameters. This is how agents discover what your store can do.
• tools/call — Executes a specific tool by name with the provided arguments. This is where the real work happens: searching products, managing carts, and processing checkouts.
• resources/read (optional) — Returns static or semi-static resources like store policies, shipping information, or category trees. Useful but not required for basic UCP support.

Tool Names

The UCP MCP binding names the tools for each capability. These are the names agents see on UCP stores today:

• search_catalog — Search products with keywords, filters, and pagination
• get_product (or lookup_catalog) — Fetch full product information, variants, and availability
• create_cart / update_cart / get_cart — Build and read a cart, if you declare the cart capability
• create_checkout — Start a checkout session
• update_checkout — Set buyer info, fulfillment, and payment details on a checkout
• get_checkout / cancel_checkout — Read or cancel a checkout session
• complete_checkout — Finalize the order and process payment

Older Shopify-style names such as search_shop_catalog and get_product_details are still recognised.

The Agent Profile on Each Call

UCP Playground sends its agent profile with every tools/call in params._meta["ucp-agent"].profile. If your tool schemas declare a meta input property, it also puts the profile in arguments.meta. Requests are signed; see Agent Identity & Webhooks for how to verify them.

Request and Response Format

Here is a complete example of a tools/call request to search for products, along with the expected response structure:

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "query": "organic coffee"
    },
    "_meta": {
      "ucp-agent": { "profile": "https://ucpplayground.com/.well-known/ucp-agent" }
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": { "version": "2026-08-25" },
      "products": [
        { "id": "123", "title": "Ethiopian Yirgacheffe", "price_range": { "min": { "amount": 1899, "currency": "USD" } } }
      ]
    },
    "content": [
      { "type": "text", "text": "{\"products\":[{\"id\":\"123\", ...}]}" }
    ]
  }
}

Return the response payload in structuredContent. You may also mirror a serialized copy into the content array for clients that don't read structured results. UCP Playground reads structuredContent first and falls back to the text in content, so if you only send text, make it a valid JSON string.

Error Responses

When a tool call fails, return a JSON-RPC error with an appropriate code. The most common error codes are -32601 (method not found), -32602 (invalid params), and -32603 (internal error). Include a descriptive message so agents can adapt their behavior or relay useful information to the user.