Catalog - MCP Binding

This document specifies the Model Context Protocol (MCP) binding for the Catalog Capability.

Protocol Fundamentals

Discovery

Businesses advertise MCP transport availability through their UCP profile at /.well-known/ucp.

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "mcp": {
          "schema": "https://ucp.dev/2026-01-11/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/ucp/mcp"
        }
      }
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{"version": "2026-01-11"}],
      "dev.ucp.shopping.catalog.lookup": [{"version": "2026-01-11"}]
    }
  }
}

Request Metadata

MCP clients MUST include a meta object in every request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "catalog": {
        "query": "blue running shoes"
      }
    }
  }
}

The meta["ucp-agent"] field is required on all requests.

Tools

Tool	Capability	Description
`search_catalog`	Search	Search for products.
`lookup_catalog`	Lookup	Lookup one or more products or variants by identifier.

`search_catalog`

Maps to the Catalog Search capability.

Search Example

=== “Request”

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "catalog": {
        "query": "blue running shoes",
        "context": {
          "address_country": "US",
          "address_region": "CA"
        },
        "filters": {
          "categories": ["Footwear"],
          "price": {"max": 15000}
        },
        "pagination": {"limit": 20}
      }
    }
  }
}
```

=== “Response”

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-01-11",
        "capabilities": {
          "dev.ucp.shopping.catalog.search": [{"version": "2026-01-11"}]
        }
      },
      "products": [
        {
          "id": "prod_abc123",
          "title": "Blue Runner Pro",
          "price_range": {
            "min": { "amount": 12000, "currency": "USD" },
            "max": { "amount": 12000, "currency": "USD" }
          },
          "variants": [
            {
              "id": "prod_abc123_size10",
              "title": "Size 10",
              "price": { "amount": 12000, "currency": "USD" },
              "availability": { "available": true }
            }
          ]
        }
      ],
      "pagination": {
        "cursor": "eyJwYWdlIjoxfQ==",
        "has_next_page": true,
        "total_count": 47
      }
    }
  }
}
```

`lookup_catalog`

Maps to the Catalog Lookup capability.

Lookup Example

=== “Request”

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lookup_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "catalog": {
        "ids": ["prod_abc123", "var_xyz789"],
        "context": {"address_country": "US"}
      }
    }
  }
}
```

=== “Response”

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-01-11",
        "capabilities": {
          "dev.ucp.shopping.catalog.lookup": [{"version": "2026-01-11"}]
        }
      },
      "products": [
        {
          "id": "prod_abc123",
          "title": "Blue Runner Pro",
          "variants": [
            {
              "id": "prod_abc123_size10",
              "title": "Size 10",
              "price": { "amount": 12000, "currency": "USD" },
              "availability": { "available": true },
              "inputs": [
                { "id": "prod_abc123", "match": "featured" }
              ]
            }
          ]
        },
        {
          "id": "prod_def456",
          "title": "Trail Master X",
          "variants": [
            {
              "id": "var_xyz789",
              "title": "Size 11 - Green",
              "price": { "amount": 15000, "currency": "USD" },
              "availability": { "available": true },
              "inputs": [
                { "id": "var_xyz789", "match": "exact" }
              ]
            }
          ]
        }
      ]
    }
  }
}
```

Error Handling

Transport Errors

Use JSON-RPC 2.0 error codes for protocol-level issues:

Code	Meaning
-32600	Invalid Request - Malformed JSON-RPC
-32601	Method not found
-32602	Invalid params - Missing required parameter
-32603	Internal error

Business Outcomes

All application-level outcomes return a successful JSON-RPC result with the UCP envelope and optional messages array.

Conformance

A conforming MCP transport implementation MUST:

Implement JSON-RPC 2.0 protocol correctly.
Implement tools for each catalog capability advertised in the business’s UCP profile.
Use JSON-RPC errors for transport issues; use messages array for business outcomes.
Return successful result for lookup requests; unknown identifiers result in fewer products returned.
Validate tool inputs against UCP schemas.
Return products with valid Price objects (amount + currency).
Support cursor-based pagination with default limit of 10.
Return -32602 (Invalid params) for requests exceeding batch size limits.