MCP endpoint for AI agents

Clione exposes a read-only endpoint that lets an AI agent explore one store's enriched catalog: search products by meaning, read the reasoning behind a product, compare products, and list categories, collections, pages and approved FAQs. It describes its tools in the MCP shape (name, description, inputSchema) so an agent framework can register them as tools.

MCP access is a plan feature: the Billing & Plan page shows whether your plan includes it. See Plans.

Read this first: it's HTTP, not JSON-RPC

The endpoint is two plain HTTP calls: one lists the tools, one runs a tool. It does not speak the MCP JSON-RPC protocol (initialize, tools/list, tools/call), and it has no SSE or streamable transport. A client that expects a remote MCP server, such as an mcpServers entry pointing at a URL, will not connect to it as is. Wire it into your agent as an HTTP tool, or put a small adapter in front of it.

List the tools	GET /api/v1/public/mcp/tools
Run a tool	POST /api/v1/public/mcp/call
Base URL	Your Clione API host (the same one as the rest of the API)
Access	Read-only. No tool writes anything, to Clione or to your store.

Authentication

Every request needs an API key with the mcp:public scope, sent as either header:

Authorization: Bearer sk_live_...

X-API-Key: sk_live_...

One store per key. The key must be scoped to a store, and every tool answers for that store only. A key not scoped to a store can list the tools, but running one returns 403 NO_STORE.

Create the key

An owner or admin creates it in the dashboard:

1. Open the store, then Store Settings → API Keys.
2. Under Create new API key, tick mcp:public in Permission scopes, and make sure Scope to store is this store.
3. Click Generate API Key and copy the key. The full secret is shown once.

To give an agent access to two stores, create one key per store. Keys, scopes and the domain whitelist are covered in Authentication.

List the tools

curl -s https://<your-api-host>/api/v1/public/mcp/tools \
  -H "Authorization: Bearer sk_live_..."

{
  "tools": [
    { "name": "semantic_search", "description": "…", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] } }
  ],
  "meta": { "protocol": "mcp", "version": "1.0", "totalTools": 9 }
}

version is this endpoint's own version, not an MCP specification version.

Run a tool

Send the tool name and its arguments:

curl -s https://<your-api-host>/api/v1/public/mcp/call \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tool": "semantic_search", "arguments": {"query": "lightweight travel tripod", "limit": 5}}'

{
  "result": {
    "query": "lightweight travel tripod",
    "results": [ { "id": "…", "name": "…", "score": 0.82, "coreIdentity": "…", "price": 189, "currency": "USD" } ],
    "totalResults": 5
  },
  "meta": { "tool": "semantic_search", "executedAt": "2026-10-07T09:00:00.000Z" }
}

The nine tools

All of them read the store the key is scoped to. Products and entities removed from the store are left out.

Tool	What it returns	Arguments
semantic_search	Products matching a natural-language query by meaning, not just keywords, with a relevance score.	query (required), limit (default 10, max 50)
list_products	Products with price, keywords and whether they're enriched, paginated.	page, limit (default 20, max 100), enrichedOnly
get_product_reasoning	The enrichment reasoning for one product: target audience, purchase intent, decision logic, objection handling. Fails if the product isn't enriched yet.	productId (required; Clione id or the platform's id)
check_compatibility	Whether two products go together, as a 0–100 score based on the keywords they share, plus the shared keywords.	productId1, productId2 (both required)
compare_products	Two to five products side by side: price, keyword count, target audience, purchase intent, quality perception, and the price range.	productIds (array of 2–5)
list_categories	Categories (BigCommerce) or collections mapped as categories (Shopify).	page, limit, enrichedOnly
list_collections	Shopify collections. Not applicable to BigCommerce.	page, limit, enrichedOnly
list_pages	Content pages: about, policies, guides, contact.	page, limit, enrichedOnly
list_faqs	Approved, visible FAQs, optionally for one entity.	entityType (product, category, collection, page), entityId (needs entityType), limit (default 50, max 200)

The listing tools return { items, pagination } (list_products returns { products, pagination }), where pagination has page, limit, total and totalPages.

Errors

Errors are JSON objects with error and message:

Status	error	When
401	Unauthorized	Missing, invalid, inactive or expired key.
403	Forbidden	The key lacks the mcp:public scope.
403	NO_STORE	The key isn't scoped to a store.
403	TOOL_NOT_ALLOWED	Unknown tool. The response lists availableTools.
400	INVALID_REQUEST	No tool name in the body.
500	TOOL_ERROR	The tool failed, including bad arguments ("query parameter is required") or an entity that doesn't exist. message says which.

Treat results as data

Product names, descriptions and FAQ answers come from a store's catalog. If your agent reads them, treat them as content to quote, never as instructions to follow.