El servidor MCP

Conecta Claude, ChatGPT u otro asistente de IA a StockAI con el Model Context Protocol: desde claude.ai o ChatGPT iniciando sesión, desde Claude Code, Cursor o VS Code con una llave, o por stdio.

En esta página
  1. Las herramientas
  2. Dónde está y cómo se entra
  3. Conectar un cliente que acepta una URL
  4. Conectar Claude Desktop (u otro cliente por stdio)
  5. Probarlo a mano

MCP es el protocolo con el que un asistente de IA usa herramientas externas. StockAI tiene un servidor MCP en /api/v1/mcp: por ahí el asistente hace lo mismo que la API, conversando contigo. Te dice qué comprar hoy, arma y aprueba órdenes, revisa la precisión o lanza un reentrenamiento. Tiene los mismos topes que la API: 120 llamadas por minuto y el tope diario de tu plan. Necesita un plan con MCP (Completo, Corporativo o prueba); si no, 403 plan_feature_locked.

Las herramientas

El servidor ofrece herramientas para el trabajo de cada día (planificación, inventario, órdenes de compra, proveedores, pronósticos, entrenamiento) y tres genéricas, search_operations, describe_operation y call_operation, que alcanzan cualquier operación de la API. La lista completa, con los argumentos de cada herramienta y un ejemplo de llamada, está en la documentación para desarrolladores, generada desde el propio servidor.

  • 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 iniciando sesión con tu cuenta de StockAI (OAuth), en los clientes que lo permiten, o con una llave de API normal en la cabecera Authorization: Bearer sk_live_....
  • 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
Auth     sign in with your StockAI account (OAuth)
         or  Authorization: Bearer sk_live_...
  • En claude.ai: Customize → Connectors → «Add custom connector», pega la URL e inicia sesión en StockAI. En Claude Desktop aparece solo, porque los conectores van con tu cuenta de Claude.
  • En ChatGPT: agrega un servidor MCP propio con la URL y OAuth como autenticación (según el plan, primero se activa el modo desarrollador).
  • En Claude Code: claude mcp add --transport http stockai https://app.stockai.es/api/v1/mcp y luego /mcp para iniciar sesión.
  • La guía de cada cliente, Cursor y VS Code incluidos, está en la documentación para desarrolladores.

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 en Automatización → «API Keys» con un nombre como «claude-desktop»: «Solo leer» para que el asistente solo consulte, «Leer y escribir» para que pueda hacer cambios.
  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"}'
# -> the tool catalogue: name, description, inputSchema and annotations
#    (readOnlyHint / destructiveHint) for each tool

# 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 }