# CatalogX MCP

Version 1.0.0

CatalogX exposes a stateless, read-only remote MCP server for product search, product facts, regional availability, and approved grounded recommendations.

**Endpoint:** http://localhost:3000/api/mcp

## Connect anonymously

```json
{
  "mcpServers": {
    "catalogx": {
      "url": "http://localhost:3000/api/mcp"
    }
  }
}
```

Anonymous clients can use catalogue read tools.

## Connect with an approved key

```json
{
  "mcpServers": {
    "catalogx": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer cxmcp_<clientId>_<secret>"
      }
    }
  }
}
```

Bearer keys are machine credentials. Keep them server-side and never expose them in browser code.

## search_catalogue

**Access:** Public · 60/10 min

Deterministic product search with regional and hard-constraint filtering.

**Input schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code, for example GH."
    },
    "query": {
      "default": "",
      "type": "string",
      "maxLength": 200
    },
    "categories": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "description": "CatalogX items ID. Examples: seating, tables-desks, beds. See the live tool schema for the complete allowed-value list."
      }
    },
    "productTypes": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "description": "CatalogX items ID. Examples: lounge-chair, dining-chair, armchair. See the live tool schema for the complete allowed-value list."
      }
    },
    "rooms": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "styles": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "colours": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "materials": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "availability": {
      "default": [
        "in_stock",
        "low_stock",
        "backorder"
      ],
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "in_stock",
          "low_stock",
          "backorder",
          "out_of_stock"
        ]
      }
    },
    "minPrice": {
      "default": null,
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "maxPrice": {
      "default": null,
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "discountOnly": {
      "default": false,
      "type": "boolean"
    },
    "maxDeliveryDays": {
      "default": null,
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 90
        },
        {
          "type": "null"
        }
      ]
    },
    "maxWidth": {
      "default": null,
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "maxHeight": {
      "default": null,
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "maxDepth": {
      "default": null,
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "sort": {
      "default": "relevance",
      "type": "string",
      "enum": [
        "relevance",
        "price_asc",
        "price_desc",
        "rating",
        "discount"
      ]
    },
    "cursor": {
      "default": null,
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "countryCode",
    "query",
    "categories",
    "productTypes",
    "rooms",
    "styles",
    "colours",
    "materials",
    "availability",
    "minPrice",
    "maxPrice",
    "discountOnly",
    "maxDeliveryDays",
    "maxWidth",
    "maxHeight",
    "maxDepth",
    "sort",
    "cursor",
    "limit"
  ],
  "additionalProperties": false
}
```

**Request**

```json
{
  "name": "search_catalogue",
  "arguments": {
    "countryCode": "GH",
    "query": "warm bedside lamp",
    "maxPrice": 800,
    "limit": 5
  }
}
```

**Response**

```json
{
  "ok": true,
  "items": [
    {
      "product": {
        "id": "product-id",
        "name": "Product name",
        "currentPrice": 620,
        "availableHere": true
      },
      "score": 41,
      "reasons": [
        "Matches lamp"
      ]
    }
  ],
  "total": 1,
  "catalogueVersion": "…",
  "nextCursor": null,
  "rateLimit": {
    "limit": 60,
    "remaining": 59,
    "reset": 1790000000000
  }
}
```

## get_product

**Access:** Public · 60/10 min

Fetch one published product by its stable ID, optionally with regional eligibility.

**Input schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "countryCode": {
      "default": null,
      "anyOf": [
        {
          "type": "string",
          "description": "CatalogX anyOf ID. Examples: AD, AE, AF. See the live tool schema for the complete allowed-value list."
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "productId",
    "countryCode"
  ],
  "additionalProperties": false
}
```

**Request**

```json
{
  "name": "get_product",
  "arguments": {
    "productId": "product-id",
    "countryCode": "GH"
  }
}
```

**Response**

```json
{
  "ok": true,
  "product": {
    "id": "product-id",
    "slug": "product-name",
    "name": "Product name",
    "availableHere": true,
    "canonicalUrl": "http://localhost:3000/store/product-name"
  },
  "rateLimit": {
    "limit": 60,
    "remaining": 58,
    "reset": 1790000000000
  }
}
```

## check_availability

**Access:** Public · 60/10 min

Check current price, stock, delivery and regional eligibility for 1–20 IDs.

**Input schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120
      }
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code, for example GH."
    }
  },
  "required": [
    "productIds",
    "countryCode"
  ],
  "additionalProperties": false
}
```

**Request**

```json
{
  "name": "check_availability",
  "arguments": {
    "productIds": [
      "product-id",
      "unknown-id"
    ],
    "countryCode": "GH"
  }
}
```

**Response**

```json
{
  "ok": true,
  "items": [
    {
      "productId": "product-id",
      "found": true,
      "currentPrice": 620,
      "stockStatus": "in_stock",
      "availableHere": true,
      "deliveryDays": 3,
      "canonicalUrl": "http://localhost:3000/store/product-name"
    },
    {
      "productId": "unknown-id",
      "found": false
    }
  ],
  "rateLimit": {
    "limit": 60,
    "remaining": 57,
    "reset": 1790000000000
  }
}
```

## recommend_products

**Access:** Approved key · 5/10 min

Run CatalogX’s grounded recommendation flow, including deterministic constraints, Jev semantic ranking, and Terra visual review.

**Input schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 2,
      "maxLength": 800
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code, for example GH."
    }
  },
  "required": [
    "prompt",
    "countryCode"
  ],
  "additionalProperties": false
}
```

**Request**

```json
{
  "name": "recommend_products",
  "arguments": {
    "prompt": "Furnish a calm reading corner under GH₵2,500",
    "countryCode": "GH"
  }
}
```

**Response**

```json
{
  "ok": true,
  "recommendationId": "…",
  "status": "reviewed",
  "mode": "products",
  "summary": "…",
  "guidance": "…",
  "products": [
    {
      "product": {
        "id": "product-id",
        "name": "Product name"
      },
      "rationale": "…",
      "reasons": [
        "…"
      ]
    }
  ],
  "suggestions": [],
  "rateLimit": {
    "limit": 5,
    "remaining": 4,
    "reset": 1790000000000
  }
}
```

## Rate limits

- Public catalogue reads: 60 calls per client per 10 minutes.
- Approved recommendations: 5 calls per client per 10 minutes.
- Successful tool responses include limit, remaining, and Unix-millisecond reset metadata. Rate-limit errors include reset metadata.

## Errors

- `INVALID_ARGUMENT`: Input or cursor failed validation.
- `NOT_FOUND`: The requested published product does not exist.
- `AUTH_REQUIRED`: A valid approved key with catalog:recommend is required.
- `RATE_LIMITED`: The applicable tier is exhausted; use rateLimit.reset.
- `TEMPORARILY_UNAVAILABLE`: CatalogX or a required provider is temporarily unavailable.

## Privacy and grounding

Public responses exclude merchant IDs, source hashes, exact inventory counts, private storage paths, prompts, and administrative fields. Recommendation provider failure degrades to CatalogX’s grounded fallback; hard constraints remain authoritative. Tools are read-only, non-destructive, and idempotent.

## Service and support

- [Human documentation](http://localhost:3000/agent/mcp)
- [Service status](http://localhost:3000/agent/mcp#service-status)
- [Support](mailto:hello@bashbashlabs.com)