Documentation

MCP Server

Connect your AI agent to live Shopify and Amazon inventory data via the Model Context Protocol. 49 ReplenishRadar tools plus knowledge search. Bearer token auth. 5-minute setup.

Quick Start

Generate an API key in Settings > API Keysinside your ReplenishRadar dashboard, then add the npm MCP package to your agent’s MCP configuration:

{
  "mcpServers": {
    "replenishradar": {
      "command": "npx",
      "args": ["-y", "@replenishradar/mcp-server"],
      "env": {
        "REPLENISHRADAR_API_KEY": "rr_sk_your_key_here"
      }
    }
  }
}

That’s it. Your local MCP server now has access to the tools allowed by your tier, capabilities, and selected tool groups.

No-signup sandbox

Evaluating ReplenishRadar without an account? POST your fit answers to https://api.replenishradar.com/api/public/agent-intake. A positive Tier B result can return a one-time, 24-hour read-only key for a shared synthetic demo organization. It cannot access production tenant data, and responses are tagged sandbox=true. If capacity or attribution persistence is unavailable, no key is issued; retry later or start a trial. Never publish the key.

Compatible Agents

Any MCP-compatible client that can run a local stdio server works out of the box: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and OpenClaw. Non-MCP agents can call the same tools via the REST API (see REST API below).

Authentication

The npm MCP package reads your key from REPLENISHRADAR_API_KEY and sends it as a Bearer token. Direct REST requests use the Authorization header. API keys use the rr_sk_ prefix and are scoped to a single organization.

Authorization: Bearer rr_sk_your_key_here

Key Properties

  • Organization-scoped - each key is bound to one organization. No cross-org access.
  • Capabilities - keys grant selected capabilities such as read, basic_write, sensitive_read, and sensitive_write. Write tools also require the matching tool group.
  • SHA-256 stored - we never store your raw key. If you lose it, generate a new one.
  • Revocable - revoke any key instantly from Settings.
  • Optional expiry - set an expiration date when creating the key.

Circuit Breaker

Abnormal bursts can temporarily suspend a key. The org owner receives an email notification, and keys resume automatically after the suspension period.

Rate Limits & Tiers

API access and rate limits are determined by your organization’s plan:

PlanPriceAccessCalls/hrWrite ToolsNotifications
Standard$99/moread + basic_write10/hrBasic-write tools only when selected on the key0
Growth$199/moread + basic_write + sensitive_read + sensitive_write100/hrCapability and tool-group gated3
Scale$499/moread + basic_write + sensitive_read + sensitive_write1,000/hrCapability and tool-group gatedUnlimited
EnterpriseCustomread + basic_write + sensitive_read + sensitive_writeUnlimitedCapability and tool-group gatedUnlimited

Trial and free-preview accounts do not have API access.View pricing →

REST API

Non-MCP agents can call tools directly via HTTP POST:

POST https://api.replenishradar.com/api/mcp/call
Authorization: Bearer rr_sk_your_key_here
Content-Type: application/json

{
  "tool": "rr_get_stockout_risk",
  "input": {
    "risk_level": "high",
    "limit": 10
  }
}

The response is a JSON object with the tool’s output. Error responses use standard HTTP status codes: 401 (auth), 403 (capability or tier), 429 (rate limit).

Read Tools (29)

Available to API keys with the read capability.

rr_get_stockout_risk

Get items at risk of stocking out, sorted by days to stockout. Filter by risk level, SKU, or store.

rr_get_inventory_position

Get stock-by-location breakdown for a single item. Returns on-hand quantities across all warehouses and stores.

rr_get_demand_forecast

Get demand forecast statistics (mu/sigma) for a SKU or item. Returns active forecast windows.

rr_get_suggested_purchase_orders

Get system-generated purchase order suggestions based on demand forecasts and stockout risk.

rr_get_replenishment_actions

List canonical buyer work across supplier PO, transfer, combined, and no-action replenishment outcomes. Prefer this over suggested purchase orders or alerts for deciding what action to take next.

rr_get_replenishment_action

Get one replenishment action with child item provenance, immutable snapshots, linked execution records, and event history.

rr_get_alerts

Get inventory alerts (stockout warnings, sync failures, reorder points). Supports filtering by type, severity, status, and SKU.

rr_list_items

List catalog items with optional search, vendor filtering, and pagination. Returns SKU, display name, lead time, and supplier info.

rr_get_sync_status

Get recent data sync runs (Shopify, Amazon). Returns sync status, timing, and error details.

rr_list_suppliers

List all suppliers/vendors for the organization. Optionally include vendor SKU mappings.

rr_list_purchase_orders

List purchase orders with filtering by status, vendor, and search. Supports pagination.

rr_get_purchase_order

Get a single purchase order with full details including line items and vendor info.

rr_get_po_pdf

Get the PDF generation endpoint for a purchase order.

rr_get_po_documents

List documents attached to a purchase order (invoices, packing slips, etc.).

rr_get_po_notes

Get notes/comments on a purchase order.

rr_get_sales_history

Get daily sales history (units sold, revenue) for a SKU or store over a date range.

rr_get_top_sellers

Get top-selling SKUs ranked by units sold over a date range.

rr_get_slow_movers

Overstock / dead-stock / slow movers: SKUs you are holding (on-hand > 0) that aren't selling. Returns on_hand, units sold in the window, and a dead_stock flag. Inventory-first, so never-sold dead stock is surfaced too.

rr_get_inventory_value

Get total inventory value and per-SKU breakdown. Cost/value fields require sensitive_read capability.

rr_get_sku_health

Get a high-level SKU health snapshot: stockout risk counts by level and active alert counts by type.

rr_get_lost_sales

Estimate lost sales from current stockouts based on demand velocity and days out of stock.

rr_get_store_health

Diagnose connected store health, sync status, and connection errors.

rr_get_data_freshness

Get data freshness by inventory dimension before quoting operational numbers.

rr_get_setup_status

Get onboarding milestones, setup completion state, and next recommended step.

rr_get_recent_activity

Get recent alerts, purchase orders, and sync activity counts.

search_knowledge

Search ReplenishRadar product knowledge for grounded answers.

rr_evaluate_fit

Evaluate whether ReplenishRadar fits your use case (deterministic ICP + tier match) and capture demand signal. Mirrors the public agent-intake survey; reads no org data.

rr_get_agent_context

Get one agent context entry by namespace and key. Expired entries are omitted. The namespace must be granted to this API key by a human admin.

rr_list_agent_context

List live agent context entries for a single namespace. The namespace is required and the limit is bounded (max 200). This tool never lists across namespaces.

Write Tools (21)

Require a write-scoped API key. Basic action tools are available on Standard+; direct PO creation, sync triggers, and stock mutations require Growth+. Purchase orders created by agents always require human approval before being sent to suppliers.

rr_trigger_sync

Trigger a data sync from Shopify or Amazon. Respects 5-minute cooldown to prevent spam.

rr_acknowledge_alert

Acknowledge an active alert with an optional note.

rr_create_purchase_order

Create a new purchase order (always created as draft). Include line items with SKUs and quantities.

rr_import_purchase_orders

Import open and historical purchase orders from a CSV export (Stocky / Inventory Planner migration). One row per line item, grouped by po_number; both tools' column names are recognized. Records received quantities as a snapshot only - never moves stock. Idempotent on po_number. preview defaults to true (validate without writing); pass preview=false to commit.

rr_update_purchase_order

Update a draft or in-review purchase order (notes, expected delivery date, vendor).

rr_add_po_note

Add a note/comment to a purchase order.

rr_request_approval

Request human approval for a purchase order. Returns a time-limited approval URL (15 min) to share with a team member.

rr_send_purchase_order

Mark an approved purchase order as sent. Requires prior human approval via rr_request_approval.

rr_cancel_purchase_order

Cancel a purchase order. Cannot cancel POs with status cancelled, received, or closed.

rr_add_replenishment_action_note

Add a note to a replenishment action.

rr_dismiss_replenishment_action

Dismiss a replenishment action with an optional reason.

rr_prepare_replenishment_action

Preview a replenishment action and return its current updated_at before executing. Use the returned updated_at as expected_updated_at on execute/resolve/retry.

rr_execute_replenishment_action

Execute a replenishment action in draft mode: creates a draft purchase order and/or draft transfer order for the action's items. Idempotent by idempotency_key; rejects with conflict if the action changed since prepare (stale expected_updated_at) or if the same key is reused with a different payload or actor. Never auto-sends to suppliers and never commits stock.

rr_resolve_replenishment_action

Resolve a replenishment action as no-action with a reason. Idempotent; requires idempotency_key and expected_updated_at and applies the same stale-state conflict contract as execute.

rr_retry_replenishment_action

Retry a blocked or failed replenishment action by re-running the draft execution path. Idempotent; requires idempotency_key and expected_updated_at and applies the same stale-state conflict contract as execute.

rr_get_document_upload_url

Create a document record for a purchase order (invoice, packing slip, etc.). Requires Scale tier.

rr_record_pi_review

Record proforma invoice details on a purchase order (PI number, date, total, terms).

rr_create_location

Create a manual inventory location such as warehouse, 3PL, or inbound location.

rr_set_stock_at_location

Set stock quantity for a SKU at a manual location.

rr_set_agent_context

Store a bounded JSON object under a namespace and key. The value must be a JSON object (max 16 KiB), must not contain secrets or raw PII, and ttl_seconds is optional and capped at 90 days. The namespace must be granted to this key.

rr_delete_agent_context

Delete one agent context entry by namespace and key. Records actor provenance. The namespace must be granted to this key.

Safety & Audit

  • Human-in-the-loop POs - agents can draft purchase orders, but every PO requires explicit human approval via a time-limited email link before it reaches a supplier.
  • Channel safety - agents cannot modify Shopify or Amazon listings or pricing through this MCP surface. Manual-location stock updates require a Growth+ write key and are fully audited.
  • Full audit trail - every API call is logged with the tool name, input summary, result status, and duration. View the audit log in Settings.
  • Org isolation - API keys are scoped to a single organization. Row-level security enforces data isolation at the database level.
  • Circuit breaker - automatic key suspension on abnormal request volume protects against runaway agents.

Agent-facing response metadata, tool versioning, and structured error expectations are documented in the Agent API contract notes.

Notification Channels

Configure notification endpoints for supported server events such as approved purchase orders. Stockout and sync workflows use MCP/API polling or scheduled automation today. Supported targets:

  • Slack (incoming webhook)
  • Microsoft Teams
  • Discord
  • PagerDuty
  • Raw webhook (any HTTPS endpoint)

Manage notification channels in Settings → Webhooks. Growth plans include 3 channels; Scale and Enterprise plans have no limit.

Error Handling

StatusMeaning
401Invalid, expired, or revoked API key
403Key capability, selected tool group, or tier does not include the requested tool
429Rate limit exceeded. Back off and retry after the window resets.
400Unknown tool name or invalid input parameters
500Internal error. Contact support if persistent.

Support

Questions about the MCP server or API integration? Contact us or email [email protected].