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
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_statustiene tope: trae lo más urgente primero, marcatruncatedy dice cuántos coinciden en total; el resumen cuenta todos. Filtra por señal o proveedor en vez de subirlimit.- 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/mcpen 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. UnGETa la misma dirección responde405: 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/mcpy luego/mcppara 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)
- 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.
- Copia el archivo
mcp_server/stockai_mcp.pydel código fuente de StockAI a tu computadora. Es un solo archivo de Python sin dependencias: no hace faltapip install. - 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. - En
STOCKAI_URLpon la raíz de tu instalación, sin barra final y sin/api/v1: el script agrega la ruta. - 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 }