CatalogX for agents · v1.0.0

A catalogue
that agents can use.

Search products, inspect grounded facts, check regional availability, and request reviewed recommendations through one stateless MCP endpoint.

http://localhost:3000/api/mcp

Connect

Reads work without a key.

Use an approved bearer key only when your agent needs the recommendation workflow.

Anonymous catalogue access

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

Approved recommendations

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

Keep bearer keys server-side. Never place one in browser code or a public repository.

Tools

Four focused, read-only tools.

search_cataloguePublic · 60/10 minget_productPublic · 60/10 mincheck_availabilityPublic · 60/10 minrecommend_productsApproved key · 5/10 min
01

search_catalogue

Deterministic product search with regional and hard-constraint filtering.

Public · 60/10 min

Request

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

Response

{
  "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
  }
}

Need a machine-readable reference? Use the Markdown guide.

02

get_product

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

Public · 60/10 min

Request

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

Response

{
  "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
  }
}

Need a machine-readable reference? Use the Markdown guide.

03

check_availability

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

Public · 60/10 min

Request

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

Response

{
  "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
  }
}

Need a machine-readable reference? Use the Markdown guide.

04

recommend_products

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

Approved key · 5/10 min

Request

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

Response

{
  "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
  }
}

Need a machine-readable reference? Use the Markdown guide.

Limits

Predictable by design.

Public catalogue tools share 60 calls per client per 10 minutes. Approved recommendations receive 5 calls per client per 10 minutes. Responses include limit, remaining, and millisecond 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 & grounding

Public facts, private boundaries.

Responses exclude merchant IDs, source hashes, exact inventory counts, private storage paths, model prompts, and administrative fields.

Provider failures fall back to grounded CatalogX behavior. Hard constraints remain authoritative. Every tool is read-only, non-destructive, and idempotent.

Service status: available when this page and the endpoint respond. Temporary provider failures return TEMPORARILY_UNAVAILABLE.

Support: hello@bashbashlabs.com