Returns Intelligence

Overview

The MCP server exposes the read-only v1 endpoints as agent tools. It speaks JSON-RPC 2.0 over a single POST to /api/v1/mcp (stateless streamable HTTP, no SSE stream and no sessions). Every tool call dispatches into the matching REST endpoint, so scopes, per-plan quotas, tenant isolation, and the return-rate metric contract are identical to calling the API directly. Because it is just a client of your own API, anything the tools return also matches the dashboard.

New to MCP? It is an open standard for connecting AI assistants to external tools and data. Add the server once in your client’s config and the assistant can call these tools on your behalf. The REST reference documents the same data if you would rather call it yourself.

Connect a client

Create an API token in workspace settings (Settings → Developer), then add the server to your MCP client’s config. Clients that support remote HTTP servers can point straight at the URL with an Authorization header:

{
  "mcpServers": {
    "returnsintel": {
      "url": "https://app.returnsintel.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer rda_live_api_tok_..."
      }
    }
  }
}

For a client that only launches local (stdio) servers, bridge to the remote endpoint with mcp-remote:

{
  "mcpServers": {
    "returnsintel": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app.returnsintel.com/api/v1/mcp",
        "--header", "Authorization: Bearer rda_live_api_tok_..."
      ]
    }
  }
}

Tools

list_entities

List or search catalog entities (SKUs, products, product groups). Enumerates the whole catalog with cursor pagination, or ranks matches with q.

Arguments: q, type, vendor, limit, cursor

read:dashboard

get_summary

Sold units, returned units, and return rate for one entity over a month range.

Arguments: sku | product_gid | product_group_type + product_group_key, start_month, end_month, window

read:dashboard

get_report

The full report for one entity: monthly trend, return reasons, refunds, timing buckets, and costs.

Arguments: selector, start_month, end_month, window, include_incomplete

read:reports

get_timeseries

The monthly return-rate series for one entity, one row per order-cohort month.

Arguments: selector, start_month, end_month, window, include_incomplete

read:reports

get_return_rate_leaderboard

SKUs ranked by highest return rate (the workspace's worst performers), with optional filters.

Arguments: period, limit, min_return_rate, min_sold_units, vendor

read:dashboard

get_return_cost_leaderboard

SKUs ranked by returns cost in money terms over a month range.

Arguments: start_month, end_month, window, limit, min_cost, vendor

read:dashboard

list_alerts

The workspace alert feed: watchlist spikes, backfill completions, connection staleness, and report-ready events.

Arguments: since, category, limit, cursor

read:alerts

Argument names and types match the REST query parameters; see the OpenAPI contract for the full schema of each.

Authentication

Authentication is the same bearer token as the REST API, sent in the Authorization header. A valid, entitled token is required to open an MCP session, and each tools/call additionally enforces the wrapped endpoint’s scope (shown per tool above) and counts against the same daily quota. Grant a token only the scopes the agent needs, for example read:dashboard and read:alerts for a monitoring agent.

Protocol

The server implements initialize, ping, tools/list, and tools/call. It replies to each request with a single JSON-RPC response; there is no server-sent event stream and no session state to manage.

JSON-RPC notifications (a message with no id, such as notifications/initialized) are acknowledged with 202 and no body. Batch requests are not supported. A GET returns 405; always POST.

A tools/call result wraps the REST response as text content: { content: [{ type: "text", text }], isError }. When the wrapped endpoint returns an error status, isError is true and the text is the structured error body.

Example flow

List the tools, then call one. (Your MCP client does this for you; the raw calls are shown for reference.)

List tools

curl -sS "https://app.returnsintel.com/api/v1/mcp" \
  -H "Authorization: Bearer $RETURNS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool

curl -sS "https://app.returnsintel.com/api/v1/mcp" \
  -H "Authorization: Bearer $RETURNS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_return_rate_leaderboard",
      "arguments": { "period": "year", "min_return_rate": 0.3, "limit": 10 }
    }
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"data\":{\"rows\":[ ... ]},\"meta\":{ ... }}" }
    ],
    "isError": false
  }
}

Errors

Transport and protocol problems return a JSON-RPC error object. Problems with a specific tool call (a 4xx from the wrapped endpoint, such as a missing scope or invalid arguments) come back as a normal result with isError: true, so the agent can read the message and adjust.

Code	Meaning
-32700	Request body was not valid JSON.
-32600	Invalid request (including batch requests, which are not supported).
-32601	Unknown method.
-32602	Unknown tool, or invalid params.
-32001	Authentication failed (missing, invalid, or unentitled token).

REST API reference OpenAPI contract