Developer platform

Cellaria API + MCP

Integra inteligencia comercial agregada del vino en agentes, CRM y BI con contratos explícitos de acceso, privacidad y consumo.

Abrir explorer Config MCP

REST local: http://localhost:4181
MCP transport: stdio · JSON-RPC 2.0
Datos: Demo sintética local

static_demo_pages identifica la demo, no autoriza llamadas. El explorer usa recursos públicos. Los endpoints comerciales requieren una API key de servidor.

Workspace de Cellaria con pregunta comercial, evidencia y caveats — Destino de producto **De señal agregada a decisión revisable**

Quickstart

Tu primer request público

Comprueba el servicio sin crear cuenta ni enviar cabeceras de autenticación.

Request

curl --silent http://localhost:4181/v1/health

200 · application/json

{
  "ok": true,
  "service": "market-winerim-api",
  "mode": "local-prototype",
  "timestamp": "2026-07-14T10:15:00.000Z"
}

FormatoJSON UTF-8

Auth contratadaX-API-Key

Rate limitsCabeceras por cliente

PrivacidadAgregado · N ≥ 5

API explorer

Ejecuta la superficie pública

Las llamadas salen desde este navegador al mismo origen. No se envía X-API-Key.

Estado básico del servicio. key id: static_demo_pages

Request

GET http://localhost:4181/v1/health
Accept: application/json

Response

Listo

Selecciona un recurso público y ejecuta la llamada.

MCP tools

Cuatro herramientas comerciales

El catálogo visible se carga desde el mismo JSON que usa el servidor stdio.

Cargando contrato MCP…

tools/call

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cellaria_compare_wines","arguments":{"wines":["El Anejón","Alion"],"region":"Madrid"}}}

Resultado estructurado

{
  "schema_version": "cellaria_mcp_wine_comparison_v1",
  "rows": [
    { "name": "El Anejón", "pvp_p50_eur": 89 },
    { "name": "Alion", "pvp_p50_eur": 98 }
  ],
  "sample": { "n": null, "status": "synthetic_demo_no_live_sample" },
  "metering": { "unit": "wine_comparison", "billed": false }
}

Casos de integración

Agentes, CRM y BI

Elige la superficie según el trabajo: MCP para agentes, REST para sistemas operativos.

MCP stdio · conversación asistida

Claude prepara la lectura y deja la decisión en manos del equipo.

Úsalo para comparar referencias, explorar productos o generar un borrador de informe con caveats antes de cualquier envío comercial.

Claude descubre las cuatro herramientas.
Cellaria devuelve datos sintéticos, evidencia y límites.
Una persona revisa el borrador y decide el siguiente paso.

.mcp.json

{
  "mcpServers": {
    "cellaria": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/GOIKO/Documents/Playground/market-winerim/scripts/cellaria-mcp-server.mjs"],
      "env": { "CELLARIA_MODE": "demo" }
    }
  }
}

MCP stdio · flujo técnico

Codex conecta análisis comercial con el repositorio.

Úsalo para validar payloads, crear fixtures CRM/BI o probar flujos sin repartir una credencial productiva al proceso local.

Configura el servidor en un proyecto confiable.
Limita la allow list a las cuatro herramientas Cellaria.
Mantén aprobación manual para borradores comerciales.

config.toml

[mcp_servers.cellaria]
command = "node"
args = ["/Users/GOIKO/Documents/Playground/market-winerim/scripts/cellaria-mcp-server.mjs"]
cwd = "/Users/GOIKO/Documents/Playground/market-winerim"
enabled_tools = [
  "cellaria_ask",
  "cellaria_compare_wines",
  "cellaria_list_products",
  "cellaria_generate_report_request"
]
default_tools_approval_mode = "prompt"

REST · servidor a servidor

Convierte una cuenta CRM en una pregunta trazable.

El backend del CRM llama a la API, conserva answer_id, evidencia y caveats, y requiere aprobación antes de crear un informe.

Construye la pregunta desde datos no sensibles de la cuenta.
Guarda señal agregada, cobertura y unidad de uso.
No copies identidades, stock, margen o ventas exactas en notas.

Node.js backend

const response = await fetch(
  `${process.env.CELLARIA_BASE_URL}/v1/market/ask`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.CELLARIA_API_KEY
    },
    body: JSON.stringify({
      question: "¿Qué referencias priorizar para Madrid?",
      buyer_type: "distributor",
      region: "madrid",
      period: "90d"
    })
  }
);

REST + CSV · datasets gobernados

Alimenta BI sin perder muestra, periodo ni privacidad.

Usa benchmarks, índices o exportaciones agregadas y conserva metadatos de cobertura para no mezclar snapshots incomparables.

La credencial vive en gateway o secret manager.
Cada fila conserva periodo, n, cobertura y estado de privacidad.
Los dashboards públicos nunca llaman directamente a endpoints contratados.

Export CSV

curl --silent \
  --header "X-API-Key: $CELLARIA_API_KEY" \
  "https://api.market.winerim.wine/v1/market/export?scope=pricing&region=madrid&period=90d" \
  --output cellaria-pricing-madrid.csv

REST API

Mapa de operaciones comerciales

Abrir contrato OpenAPI

Operación	Endpoint	Scope	Resultado
GET Comparar	`/v1/market/compare`	`market:read`	2 o 3 referencias agregadas
POST Preguntar	`/v1/market/ask`	`market:read`	Respuesta, evidencia y caveats
GET Productos	`/v1/market/report-packages`	`market:read`	Paquetes comercializables
POST Solicitar	`/v1/market/report-requests`	`market:read`	Solicitud persistente y trazable
GET Uso	`/v1/market/usage`	`usage:read`	Cuota y consumo del cliente

Autenticación contratada

La clave termina en el backend.

Las claves se provisionan por cliente y se almacenan hasheadas en Cellaria. En el consumidor se inyectan desde entorno o secret manager.

X-API-Key: $CELLARIA_API_KEY
Content-Type: application/json

SDK y recetas

Seis puntos de partida ejecutables

Cada ejemplo conserva autenticación server-side, evidencia y límites de privacidad.

Node.js

Cliente mínimo para overview, Ask, report requests y watchlists.

Abrir cliente

Python

Cliente sin dependencias externas para scripts y notebooks internos.

Abrir cliente

Claude y Codex

Prompts MCP con contrato de evidencia, caveats, lineage y guardrails.

Abrir prompts

CRM

Webhook CRM

Mapea una solicitud Cellaria a cuenta, producto, decisión y siguiente acción.

Abrir webhook

Export BI

Exporta filas agregadas a CSV sin perder el ámbito gobernado.

Abrir exportador

MCP

Configuración MCP

Plantilla de servidor para agentes con credencial inyectada por entorno.

Abrir config

Gobernanza

Acceso y privacidad por diseño

El contrato distingue documentación pública, inteligencia contratada y operación interna.

Acceso

Público: health, readiness, OpenAPI, planes y catálogo demo.

Contratado: endpoints market con scopes y cuota por cliente.

Interno: ingesta y operaciones con permisos separados.

Privacidad

N ≥ 5 antes de publicar buckets reales. La identidad del restaurante permanece oculta sin permiso.

Coste, stock, margen y ventas se entregan como rangos, índices o agregados autorizados.

Claims

Presencia no es venta. PVP no es margen. La cobertura parcial no representa todo el mercado.

Se bloquean cuota total, ranking absoluto y predicciones de venta garantizadas.

Petición bloqueada “Dame nombres de restaurantes y sus ventas exactas.”

Alternativa segura “Compara presencia y PVP por buckets anónimos con N ≥ 5.”

Metering

Cada salida declara qué consume

La demo local muestra unidades pero no escribe ledger ni genera facturación.

Demo key id: static_demo_pages
Credential: null
Billable: false
Ledger: disabled

market_answerRespuesta comercial preparada

wine_comparisonComparación de dos o tres vinos

product_catalog_readLectura de catálogo comercial

report_request_draftBorrador local sin envío

Producción

La cuota efectiva viene del contrato.

Consulta GET /v1/market/usage con usage:read y las cabeceras X-RateLimit-*. No infieras precio o límites a partir de esta demo.

Leer guía completa