The MCP server

Connect Claude, ChatGPT or another AI assistant to StockAI with the Model Context Protocol: from claude.ai or ChatGPT by signing in, from Claude Code, Cursor or VS Code with a key, or over stdio.

On this page
  1. The 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: through it the assistant does what the API does, in conversation with you. It tells you what to buy today, drafts and approves orders, checks accuracy or starts a retrain. It has the API's ceilings: 120 calls per minute and your plan's daily ceiling. It needs a plan with MCP (Full, Corporate or trial); otherwise 403 plan_feature_locked.

The tools

The server offers tools for the daily work (planning, inventory, purchase orders, suppliers, forecasts, training) and three generic ones, search_operations, describe_operation and call_operation, that reach any operation of the API. The full list, with each tool's arguments and an example call, is in the developer documentation, generated from the server itself.

  • 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 by signing in with your StockAI account (OAuth), in clients that support it, or with an ordinary API key in the Authorization: Bearer sk_live_... header.
  • 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
Auth     sign in with your StockAI account (OAuth)
         or  Authorization: Bearer sk_live_...
  • In claude.ai: Customize → Connectors → "Add custom connector", paste the URL and sign in to StockAI. Claude Desktop shows it too, because connectors belong to your Claude account.
  • In ChatGPT: add a custom MCP server with the URL and OAuth as the authentication (on some plans you turn on developer mode first).
  • In Claude Code: claude mcp add --transport http stockai https://app.stockai.es/api/v1/mcp, then /mcp to sign in.
  • The guide for each client, Cursor and VS Code included, is in the developer documentation.

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 key under Automation → "API Keys" with a name such as "claude-desktop": "Read only" for an assistant that only looks things up, "Read and write" to let it make changes.
  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"}'
# -> 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 }