Guía
API de Nuira: el servidor MCP para asistentes de IA y automatizaciones
Referencia de la API de solo lectura de Nuira en api.nuira.ai/mcp, la que usan Claude, ChatGPT, Zapier y Slack. Autenticación, peticiones, herramientas y límites.
Actualizado: 15 de octubre de 2026
Nuira tiene una sola API, de solo lectura: un servidor Model Context Protocol (MCP). Claude, ChatGPT, Slack y Zapier se conectan a él, y puedes llamarlo desde tu propio código. Cada herramienta devuelve las mismas cifras que muestra el panel de Nuira, siempre de una sola marca.
Endpoint
| URL | https://api.nuira.ai/mcp |
| Transporte | MCP Streamable HTTP, sin estado, con respuestas JSON (POST) |
| Protocolo | JSON-RPC 2.0. Admite initialize, tools/list, tools/call, prompts/list, prompts/get, resources/list y resources/read |
| Límite | 60 peticiones por minuto y conexión. Por encima, la API responde 429 con Retry-After: 60 |
Envía Content-Type: application/json y
Accept: application/json, text/event-stream. El servidor no guarda sesión, así
que una petición tools/call funciona sola, sin un initialize previo.
Autenticación
Las peticiones llevan Authorization: Bearer <token>. Hay dos tipos de token.
OAuth 2.1 (asistentes e integraciones).
https://api.nuira.ai/.well-known/oauth-protected-resource/mcp indica el
servidor de autorización. Sus metadatos listan los endpoints de autorización,
token y registro. Los clientes pueden registrarse solos mediante registro
dinámico de clientes. El flujo es el de código de autorización con PKCE (S256),
y se emiten refresh tokens. Al iniciar sesión, el operador elige qué proyecto de
Nuira puede leer la conexión, y el permiso queda ligado a ese proyecto.
Tokens personales (scripts). Créalos en Ajustes → Asistentes de IA, en
Nuira. Empiezan por nuira_mcp_, se muestran una sola vez y leen el proyecto en
el que se crearon.
Una petición sin un token válido recibe 401 y un desafío WWW-Authenticate que
apunta a los metadatos anteriores. Un token válido cuyo permiso nunca se aprobó,
o se revocó, recibe 403.
Ejemplo de petición
curl https://api.nuira.ai/mcp \
-H "Authorization: Bearer $NUIRA_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"get_summary","arguments":{"from":"2026-09-01","to":"2026-09-30"}}}'El resultado es una respuesta JSON-RPC. La salida de la herramienta es JSON en
result.content[0].text, y result.isError vale true cuando la herramienta
rechaza los argumentos (por ejemplo, un rango que termina después de hoy).
Herramientas
Todas son de solo lectura. Las que leen un periodo aceptan from y to
opcionales: fechas YYYY-MM-DD inclusivas, las dos o ninguna, nunca posteriores
a hoy. Sin ellas, la herramienta lee los últimos 30 días completos en la zona
horaria de la tienda. Los importes llegan en la moneda de la tienda, que cada
resultado indica.
| Herramienta | Devuelve |
|---|---|
get_data_status |
Qué fuentes están conectadas y lo recientes que son sus datos. Llámala primero: una fuente vacía son datos que faltan, no cero ventas |
get_summary |
Ingresos, inversión publicitaria, margen de contribución y ROAS combinado, con el periodo anterior, clientes nuevos y recurrentes y tasa de conversión |
get_sales_breakdown |
Las líneas de ventas de Shopify: ventas brutas, descuentos, devoluciones, ventas netas, envío e impuestos |
get_contribution_breakdown |
De ingresos netos a margen de contribución: coste de producto, beneficio bruto e inversión publicitaria |
get_margin_trend |
Margen bruto y margen tras la inversión, mes a mes |
get_series |
Ingresos e inversión diarios |
get_revenue_by_hour |
Ingresos por hora del día en los últimos 7 días |
get_channels |
Inversión, ingresos y ROAS por canal (Meta, Google Ads, Klaviyo) |
get_sales |
Ventas por campaña y canal según el modelo de atribución de Nuira |
get_money_flow |
Qué canales generan ingresos en qué productos |
get_email_performance |
Flujos y campañas de Klaviyo: ingresos, envíos, aperturas y clics |
get_product_performance |
Ingresos del catálogo, unidades, ticket medio, margen bruto y SKUs sin stock |
get_top_products |
Los diez productos con más ingresos, con coste, beneficio y margen |
get_product_categories |
Ingresos, unidades y margen por categoría |
get_inventory_health |
Stock por SKU, agrupado por días de cobertura |
list_recommendations |
Recomendaciones abiertas, ordenadas, con valor esperado y confianza |
list_insights |
Cambios semana a semana que siguen activos, los de más impacto primero |
list_insight_episodes |
Cómo evolucionó un cambio detectado, día a día |
get_business_profile |
Los márgenes y objetivos de la marca y lo que Nuira sabe de cómo funciona |
get_knowledge_coverage |
Cuánto sabe Nuira del negocio, por área |
get_fact_history |
Cómo han cambiado las cifras que guarda Nuira, con sus fuentes |
get_vertical_benchmarks |
Rangos habituales de margen y ROAS para el sector de la tienda |
get_connect_links |
Un enlace por fuente para conectarla o reconectarla en Nuira |
tools/list devuelve el JSON Schema completo y las anotaciones de cada
herramienta. El servidor también ofrece dos recursos (nuira://project/profile
y nuira://project/recommendations) y tres prompts (weekly_review,
explain_margin y budget_check).
Zapier
La integración de Nuira con Zapier se basa en estas herramientas. Tiene dos
disparadores: New Recommendation lee list_recommendations y New Insight
lee list_insights. Tiene dos búsquedas: Get Performance Summary llama a
get_summary y Get Product Performance llama a get_product_performance.
Inicia sesión con el flujo OAuth descrito arriba.
Soporte
Escribe a support@nuira.ai por un problema con una integración y a security@nuira.ai por una vulnerabilidad.