Skip to main content

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.

Which plans include it​

The endpoint is included in the Pro and Agency plans. On Starter and Growth you can add it with the MCP access add-on, on the Billing & Plan page under Add-ons — the price is shown at checkout. See Plans.

From 7 November 2026 the endpoint checks the plan. Until then it works on every plan, as it does today, and an organization on Starter or Growth whose agents use it sees a notice in the dashboard with the date. From that day, a key whose organization is on a plan without MCP access gets 403 MCP_PLAN_REQUIRED on both calls, until the organization changes plan or adds the add-on.

Besides the plan, the endpoint checks the API key described below: one of the MCP scopes and a store.

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 toolsGET /api/v1/public/mcp/tools
Run a toolPOST /api/v1/public/mcp/call
Base URLYour Clione API host (the same one as the rest of the API)
AccessRead-only. No tool writes anything, to Clione or to your store.

Authentication​

Every request needs an API key carrying one of mcp:public, mcp:access or mcp:admin, sent as either header. mcp:public is the one you can create yourself; the other two are issued by Clione support. All three reach the same read-only tools — a wider scope opens nothing extra here.

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.

ToolWhat it returnsArguments
semantic_searchProducts matching a natural-language query by meaning, not just keywords, with a relevance score.query (required), limit (default 10, max 50)
list_productsProducts with price, keywords and whether they're enriched, paginated.page, limit (default 20, max 100), enrichedOnly
get_product_reasoningThe 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_compatibilityWhether two products go together, as a 0–100 score based on the keywords they share, plus the shared keywords.productId1, productId2 (both required)
compare_productsTwo 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_categoriesCategories (BigCommerce) or collections mapped as categories (Shopify).page, limit, enrichedOnly
list_collectionsShopify collections. Not applicable to BigCommerce.page, limit, enrichedOnly
list_pagesContent pages: about, policies, guides, contact.page, limit, enrichedOnly
list_faqsApproved, 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:

StatuserrorWhen
401UnauthorizedMissing, invalid, inactive or expired key.
403ForbiddenThe key holds none of mcp:public, mcp:access, mcp:admin. The response lists them in requiredAny; you need one, not all.
403NO_STOREThe key isn't scoped to a store.
403MCP_PLAN_REQUIREDFrom 7 November 2026: the key's organization is on a plan without MCP access and has no MCP access add-on. details.addonType is mcp_access.
503PLAN_CHECK_FAILEDFrom 7 November 2026: the plan could not be checked. Retry shortly.
403TOOL_NOT_ALLOWEDUnknown tool. The response lists availableTools.
400INVALID_REQUESTNo tool name in the body.
500TOOL_ERRORThe 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.