MCP tools decision

Public Tools

server.py

• list_store() > read only -- agent tool to determine which stores are available to access
• raise_replenishment_order() > write -- provide the agent the capability to place orders on behalf of Korral
• replenishment_order_status() > read only -- agent tool to determine the status of a placed order
• sku_report() > read only -- agent tool to assess sku information, including supplier and lead time

Utility private functions (not agent tools)

server.py

• sku_lead_time() > read only (private) -- utility tool for the sku_report public tool to determine how fast an order can be fulfilled.
• stock_report(sku) > read only (private) -- compare what is in stock/on-hand vs recent post transactions for the sku

Observability

Package in observability/

1. Technical trace — for support / engineers

Structured JSON on the storelink_mcp.trace.technical logger, meant for diagnosing issues as they happen:

• Explicit MCP server version (mcp_server.name + version) on every record.
• Correlation trace_id (shared with the audit stream) and the MCP request_id.
• Tool name and business arguments (the audit-only reason is stripped out).
• Per-leg downstream spans — every StoreLink HTTP call with method, path, status, latency, and retry attempts, tagged leg: "mcp<->storelink".
• On failure: the failing connection leg (duvo<->mcp vs mcp<->storelink), the unwrapped root-cause error type/message (FastMCP wraps tool errors in a ToolError; the original StoreLinkAPIError is surfaced with wrapped_by), and the full chained stack trace.

2. Audit trace — for buyers (non-technical stakeholders)

A readable line on the storelink_mcp.trace.audit logger:

• A plain-English description of each step the agent took.
• The agent's reasoning, captured via an optional reason argument added to every public tool (the model is instructed to always provide it).
• A buyer-friendly outcome — a summary of the result on success, or a calm "this step could not be completed" note on failure (never a stack trace).
• A running step_number so the actions read in order.

Keys transactions

Each StoreLink API key (X-Korral-Store-Key) is scoped to one store id.

There are two scenarios to consider per the assessment brief: a) key rotates mid-flight and b) unknown store id is referenced.

-- For a, when a key is rotated while a request is in flight e.g. storelink api returns 40x errors, invalidate the currently stored key, reload with the newly rotated key, and retry (max 3).

-- For b, when a new or unknown store is provided, before making any request to the storelink API, inform the end user (buyer) that the store number referenced is not included in the available stores, provide them explicit written instructions to ask the Korral IT team to provision a key for the store provided.

Shipping

-- Where this runs: The MCP server will run in Korall's GCP instance via GCP Cloud Run where all the data is already internal/private. Assuming that StoreLink API also exists in the same GCP instance, all the data that comes into the MCP server is also internal/private.

-- How it gets there: The MCP server will be built as a docker image that Duvo maintains and ships out to Korral for verification before they deploy new builds/changes done by Duvo.

-- How secrets are handled: see Keys transactions section