Endpoint MCP para agentes de IA

Clione expone un endpoint de solo lectura con el que un agente de IA puede explorar el catálogo enriquecido de una tienda: buscar productos por significado, leer el razonamiento que hay detrás de un producto, comparar productos y listar categorías, colecciones, páginas y FAQs aprobadas. Describe sus herramientas con la forma de MCP (name, description, inputSchema), así que un framework de agentes puede registrarlas como herramientas.

El acceso MCP es una funcionalidad del plan: la página Facturación y plan te dice si tu plan lo incluye. Lo tienes en Planes.

Antes de nada: es HTTP, no JSON-RPC

El endpoint son dos llamadas HTTP normales: una lista las herramientas y otra ejecuta una. No habla el protocolo JSON-RPC de MCP (initialize, tools/list, tools/call) ni tiene transporte SSE o streamable. Un cliente que espere un servidor MCP remoto, como una entrada mcpServers que apunta a una URL, no se conectará tal cual. Conéctalo a tu agente como herramienta HTTP, o pon delante un pequeño adaptador.

Listar las herramientas	GET /api/v1/public/mcp/tools
Ejecutar una herramienta	POST /api/v1/public/mcp/call
URL base	Tu host de la API de Clione (el mismo que el resto de la API)
Acceso	Solo lectura. Ninguna herramienta escribe nada, ni en Clione ni en tu tienda.

Autenticación

Cada petición necesita una API key con el scope mcp:public, en cualquiera de estas dos cabeceras:

Authorization: Bearer sk_live_...

X-API-Key: sk_live_...

Una tienda por key. La key tiene que estar limitada a una tienda, y cada herramienta responde solo de esa tienda. Una key sin tienda puede listar las herramientas, pero al ejecutar una recibe 403 NO_STORE.

Crea la key

La crea un propietario o un administrador desde el dashboard:

1. Abre la tienda y ve a Ajustes de la tienda → Claves de API.
2. En Crear una clave de API, marca mcp:public en Permisos y comprueba que en Limitar a una tienda está esta tienda.
3. Haz clic en Generar clave de API y copia la key. El secreto completo solo se enseña una vez.

Para dar acceso a un agente a dos tiendas, crea una key por tienda. Las keys, los scopes y la lista de dominios permitidos están en Autenticación.

Listar las herramientas

curl -s https://<tu-host-de-la-api>/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 es la versión de este endpoint, no una versión de la especificación MCP.

Ejecutar una herramienta

Manda el nombre de la herramienta y sus argumentos:

curl -s https://<tu-host-de-la-api>/api/v1/public/mcp/call \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tool": "semantic_search", "arguments": {"query": "trípode de viaje ligero", "limit": 5}}'

{
  "result": {
    "query": "trípode de viaje ligero",
    "results": [ { "id": "…", "name": "…", "score": 0.82, "coreIdentity": "…", "price": 189, "currency": "USD" } ],
    "totalResults": 5
  },
  "meta": { "tool": "semantic_search", "executedAt": "2026-10-07T09:00:00.000Z" }
}

Las nueve herramientas

Todas leen la tienda a la que está limitada la key. Los productos y entidades que se han quitado de la tienda no aparecen.

Herramienta	Qué devuelve	Argumentos
semantic_search	Productos que encajan con una consulta en lenguaje natural por significado, no solo por palabras, con una puntuación de relevancia.	query (obligatorio), limit (10 por defecto, máximo 50)
list_products	Productos con precio, keywords y si están enriquecidos, paginados.	page, limit (20 por defecto, máximo 100), enrichedOnly
get_product_reasoning	El razonamiento del enriquecimiento de un producto: público objetivo, intención de compra, lógica de decisión, manejo de objeciones. Falla si el producto aún no está enriquecido.	productId (obligatorio; el id de Clione o el de la plataforma)
check_compatibility	Si dos productos van juntos, como una puntuación de 0 a 100 basada en las keywords que comparten, más esas keywords.	productId1, productId2 (los dos obligatorios)
compare_products	De dos a cinco productos lado a lado: precio, número de keywords, público objetivo, intención de compra, percepción de calidad y la horquilla de precios.	productIds (lista de 2 a 5)
list_categories	Categorías (BigCommerce) o colecciones tratadas como categorías (Shopify).	page, limit, enrichedOnly
list_collections	Colecciones de Shopify. No aplica a BigCommerce.	page, limit, enrichedOnly
list_pages	Páginas de contenido: quiénes somos, políticas, guías, contacto.	page, limit, enrichedOnly
list_faqs	FAQs aprobadas y visibles, opcionalmente de una sola entidad.	entityType (product, category, collection, page), entityId (necesita entityType), limit (50 por defecto, máximo 200)

Las herramientas de listado devuelven { items, pagination } (list_products devuelve { products, pagination }), donde pagination lleva page, limit, total y totalPages.

Errores

Los errores son objetos JSON con error y message:

Estado	error	Cuándo
401	Unauthorized	Falta la key, o no es válida, está inactiva o ha caducado.
403	Forbidden	La key no tiene el scope mcp:public.
403	NO_STORE	La key no está limitada a una tienda.
403	TOOL_NOT_ALLOWED	Herramienta desconocida. La respuesta lista las availableTools.
400	INVALID_REQUEST	No hay nombre de herramienta en el cuerpo.
500	TOOL_ERROR	La herramienta ha fallado, también por argumentos incorrectos ("query parameter is required") o por una entidad que no existe. message dice cuál.

Trata los resultados como datos

Los nombres de producto, las descripciones y las respuestas de las FAQs salen del catálogo de una tienda. Si tu agente los lee, que los trate como contenido que citar, nunca como instrucciones que seguir.