El servidor MCP

Conecta un asistente de IA a StockAI con el Model Context Protocol: cinco herramientas de solo lectura, por URL o con un cliente de escritorio como Claude Desktop.

MCP es el protocolo con el que un asistente de IA usa herramientas externas. StockAI tiene un servidor MCP en /api/v1/mcp: el asistente puede preguntar qué comprar hoy y responder con tus datos. Usa la misma llave sk_live_ que la API, el mismo tope de 120 llamadas por minuto y el mismo tope diario. Necesita un plan con MCP (Completo, Corporativo o prueba); si no, 403 plan_feature_locked.

Las cinco herramientas

• get_inventory_status tiene tope: trae lo más urgente primero, marca truncated y dice cuántos coinciden en total; el resumen cuenta todos. Filtra por señal o proveedor en vez de subir limit.
• Un filtro que no encuentra nada dice qué clase de vacío es (empty_reason); una señal desconocida se rechaza nombrando las válidas.
• Una negativa llega como un error de la herramienta que el asistente puede leer, con su error_code, no como un fallo de transporte.

Las herramientas le advierten al asistente que SIN_DATOS significa «no sabemos», no «está bien», y que un valor marcado como supuesto de StockAI no es un dato tuyo. Así el asistente no te presenta como tranquilo algo que nadie midió.

Dónde está y cómo se entra

• La dirección es /api/v1/mcp en el dominio de tu instalación; la pantalla API la muestra completa en «Conecta tu asistente (MCP)».
• Se entra con una llave de API normal, en la cabecera Authorization: Bearer sk_live_.... Una llave «Solo leer» alcanza para todo.
• Comparte el mismo límite que la API: 120 llamadas por minuto por llave.
• Las preguntas se mandan con POST. Un GET a la misma dirección responde 405: el servidor no abre un canal de eventos, porque todo cabe en la respuesta de cada pregunta.

Conectar un cliente que acepta una URL

URL      https://app.stockai.es/api/v1/mcp
Header   Authorization: Bearer sk_live_...

El servidor no guarda estado: no hay sesión que abrir ni conexión que mantener. Habla el transporte Streamable HTTP; las peticiones van por POST y un GET responde 405 (no hay nada que transmitir). Acepta las revisiones del protocolo 2024-11-05, 2025-03-26, 2025-06-18 y 2025-11-25.

Conectar Claude Desktop (u otro cliente por stdio)

1. Crea una llave «Solo leer» en Automatización → «API Keys» con un nombre como «claude-desktop».
2. Copia el archivo mcp_server/stockai_mcp.py del código fuente de StockAI a tu computadora. Es un solo archivo de Python sin dependencias: no hace falta pip install.
3. Abre la configuración de tu cliente (en Claude Desktop, el archivo claude_desktop_config.json) y agrega el bloque de abajo con la ruta absoluta del archivo.
4. En STOCKAI_URL pon la raíz de tu instalación, sin barra final y sin /api/v1: el script agrega la ruta.
5. Reinicia el cliente y pregúntale «¿qué compro hoy?».

{
  "mcpServers": {
    "stockai": {
      "command": "python",
      "args": ["/absolute/path/to/stockai_mcp.py"],
      "env": {
        "STOCKAI_URL": "https://app.stockai.es",
        "STOCKAI_API_KEY": "sk_live_..."
      }
    }
  }
}

El script es solo un conducto: reenvía cada mensaje a /api/v1/mcp y devuelve la respuesta. Si la llave está mal o la instalación no responde, el cliente recibe un mensaje legible en lugar de quedarse colgado.

Probarlo a mano

# 1. Handshake
curl -X POST https://app.stockai.es/api/v1/mcp \
  -H "Authorization: Bearer $STOCKAI_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'
# -> "result": { "protocolVersion": "2025-06-18",
#                "serverInfo": { "name": "stockai", ... }, "instructions": "..." }

# 2. The catalogue
curl -X POST https://app.stockai.es/api/v1/mcp -H "Authorization: Bearer $STOCKAI_KEY" \
  -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# -> get_planning_context, get_inventory_status, get_morning_briefing,
#    list_data_sources, get_training_status

# 3. A call
curl -X POST https://app.stockai.es/api/v1/mcp -H "Authorization: Bearer $STOCKAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"get_inventory_status","arguments":{"signal":"PEDIR_YA","limit":20}}}'
# -> "result": { "content": [{ "type": "text", "text": "..." }],
#                "structuredContent": { ... }, "isError": false }