The MCP server

Connect an AI assistant to StockAI with the Model Context Protocol: five read-only tools, by URL or with a desktop client such as Claude Desktop.

On this page
  1. The five tools
  2. Where it is and how to get in
  3. Connecting a client that takes a URL
  4. Connecting Claude Desktop (or another stdio client)
  5. Trying it by hand

MCP is the protocol an AI assistant uses to call outside tools. StockAI has an MCP server at /api/v1/mcp: the assistant can ask what to buy today and answer from your data. It uses the same sk_live_ key as the API, the same 120-calls-per-minute ceiling and the same daily ceiling. It needs a plan with MCP (Full, Corporate or trial); otherwise 403 plan_feature_locked.

The five tools

ToolWhat it returnsArguments
get_planning_contextThe active session, the detail (day, week, month) and the horizon. The starting point.none
get_morning_briefingThe day's work: risks, the reason behind each recommendation, suggested supplier and value.none required
get_inventory_statusThe stock signal per SKU, most urgent first.signal (PEDIR_YA, PEDIR_PRONTO, OK, SOBRESTOCK, SIN_DATOS), supplier, limit (1–500, default 50)
list_data_sourcesYour sales sources and when they were updated.limit (1–200, default 50)
get_training_statusWhether a session has finished training.session_id (required)
  • get_inventory_status is capped: it returns the most urgent first, sets truncated and reports how many match in total; the summary counts all of them. Filter by signal or supplier rather than raising limit.
  • A filter that matches nothing says which kind of empty it is (empty_reason); an unknown signal is refused with the valid ones named.
  • A refusal comes back as a tool error the assistant can read, with its error_code, not as a transport failure.

The tools warn the assistant that SIN_DATOS means "unknown", not "fine", and that a value marked as a StockAI assumption is not your own figure. That way the assistant never reports as safe something nobody measured.

Where it is and how to get in

  • The address is /api/v1/mcp on your installation's domain; the API screen shows it in full under "Connect your assistant (MCP)".
  • You get in with an ordinary API key in the Authorization: Bearer sk_live_... header. A "Read only" key is enough for everything.
  • It shares the API's limits: 120 calls per minute per key, and your plan's daily ceiling.
  • Questions are sent with POST. A GET to the same address answers 405: the server opens no event stream, because every answer fits in the response to its question.

Connecting a client that takes a URL

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

The server is stateless: no session to open, no connection to keep alive. It speaks the Streamable HTTP transport; requests go by POST and a GET answers 405 (there is nothing to stream). It accepts protocol revisions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25.

Connecting Claude Desktop (or another stdio client)

  1. Create a "Read only" key under Automation → "API Keys" with a name such as "claude-desktop".
  2. Copy the file mcp_server/stockai_mcp.py from StockAI's source code to your computer. It is a single Python file with no dependencies: no pip install needed.
  3. Open your client's configuration (in Claude Desktop, the claude_desktop_config.json file) and add the block below with the file's absolute path.
  4. In STOCKAI_URL put your installation's root, without a trailing slash and without /api/v1: the script appends the path.
  5. Restart the client and ask it "what should I buy today?".
{
  "mcpServers": {
    "stockai": {
      "command": "python",
      "args": ["/absolute/path/to/stockai_mcp.py"],
      "env": {
        "STOCKAI_URL": "https://app.stockai.es",
        "STOCKAI_API_KEY": "sk_live_..."
      }
    }
  }
}

The script is only a pipe: it forwards each message to /api/v1/mcp and returns the answer. If the key is wrong or the installation does not answer, the client receives a readable message instead of hanging.

Trying it by hand

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