List Retailers (Messaging)

messagingmcp-list_retailers

List the retailers (or regions) the messaging corpus actually covers.

Use this before a detailed query to confirm a retailer or region is present and how fresh the data is. Never suggest a retailer from memory — only reference retailers returned here. To resolve one retailer's slug, pass its name (or a fragment) as query rather than paging the whole catalogue.

Parameters

Name	Type	Required	Constraints	Description
by	string	no	default: "retailer"	Grouping. 'retailer' (default) lists each retailer with its regions and latest capture date. 'region' lists each region with the retailers present.
query	string | null	no	default: null	Case-insensitive substring to narrow the groups: matched against the retailer slug and display name (by='retailer') or the region label (by='region'). Use this to look up one retailer's slug without fetching the whole catalogue, e.g. query='zara'.
limit	integer	no	default: 100 · 1–1000	Max groups returned (default 100). The full corpus is ~2,800 retailers; total_groups reports the pre-limit match count so truncation is visible.

Returns

• On success: {"by", "total_groups", "returned", "groups": [...]} —
• total_groups counts matches before limit; if returned < total_groups,
• narrow with query rather than raising the limit.
• For by="retailer": each group is {retailer, retailer_name, regions,
• latest_date, count} — retailer is the slug to pass to the promo/visual
• filters, retailer_name the display name to match a request against.
• count is a raw document count across the promo + visual indices (a
• volume signal — NOT a promotion count; use count_promos for that);
• latest_date is the latest capture date.
• For by="region": each group is {region, retailers, latest_date}.
• On failure: {"error": str}.

Try it

Loading interactive widget…

Code examples

curl

curl -s https://mcp.edited.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: $MCP_API_KEY" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "messagingmcp-list_retailers",
    "arguments": {
      "by": "retailer",
      "query": null,
      "limit": 100
    }
  }
}'

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
    requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
  }),
);

const result = await client.callTool({
  name: "messagingmcp-list_retailers",
  arguments: {
    "by": "retailer",
    "query": null,
    "limit": 100
  },
});

Python

import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "messagingmcp-list_retailers",
            {"by": "retailer", "query": None, "limit": 100},
        )

Input schema

{
  "type": "object",
  "properties": {
    "by": {
      "default": "retailer",
      "description": "Grouping. 'retailer' (default) lists each retailer with its regions and latest capture date. 'region' lists each region with the retailers present.",
      "enum": [
        "retailer",
        "region"
      ],
      "type": "string"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Case-insensitive substring to narrow the groups: matched against the retailer slug and display name (by='retailer') or the region label (by='region'). Use this to look up one retailer's slug without fetching the whole catalogue, e.g. query='zara'."
    },
    "limit": {
      "default": 100,
      "description": "Max groups returned (default 100). The full corpus is ~2,800 retailers; `total_groups` reports the pre-limit match count so truncation is visible.",
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    }
  }
}