# EDITED MCP

> EDITED MCP connects any MCP-compatible agent to EDITED's structured retail
> data across three verticals — apparel (including footwear and accessories),
> beauty, and home — organized into three tool domains: competitive market data,
> trend research, and messaging & promotions. It serves the most recent data
> from a dataset EDITED has spent 12+ years building; the complete
> archive going further back is available through EDITED's API. One stateless
> Streamable HTTP endpoint (`https://mcp.edited.com/mcp`, `x-api-key` on every
> call, protocol `2025-06-18`).

If you are an agent meeting EDITED for the first time, read this page before you
start calling tools. EDITED's data is broad and its tools expect stable internal
identifiers rather than free-text names — a minute of orientation here saves a
lot of wrong turns. This is the warm welcome; [`/llms-full.txt`](/llms-full.txt)
is the complete text of every page if you want the whole corpus.

## What EDITED is

EDITED has spent 12+ years building one of the most comprehensive
structured datasets in retail — 90,000 brands and 5bn+ SKUs spanning **three
verticals**: apparel (including footwear and accessories), beauty, and home.
That's *what* the data covers. The MCP gateway organizes access to it across **three domains** — *how*
the tools are grouped: each domain is a separate backend namespace, plus a set of
identifier-resolution and data-quality **helpers** in the `mdmcp` namespace.

Note the access boundary: MCP serves the **most recent** data for real-time
queries. EDITED's full historical archive, going back further, is reached through
EDITED's API rather than MCP.

The server is **stateless** — there is no session to manage; send your
`x-api-key` on every call. Tools return data directly over MCP (this is not a
thin ID-lookup layer in front of a separate API).

## The one thing to get right first: resolve identifiers

Almost every query tool expects a **stable identifier** — a slug or integer id —
not a free-text name. Resolving identifiers is a required first step, not
optional pre-processing.

**For retailers, resolve the market first.** Retailer slugs are *not* globally
unique — Zara in the UK might be `zara`, not `zara-uk`, depending on when it was
added. The reliable sequence is:

1. `search_markets` to resolve the market ("UK", "US", "Germany")
2. `search_retailers` with that market's `country_code` to get the correct
   regional slug
3. use the slug in the domain query tools

Brands, categories, markets, and sizing are simpler: search, take the top
result, extract the id. Identifiers are stable — resolve once and reuse within a
session. Full walkthrough: [How to query → Identifier resolution](/how-to-query#identifier-resolution).

## The three domains

- **Competitive Market Data** (`mdmcp`) — live structured data on fashion retail
  products across thousands of retailers and brands: pricing, stock, discounts,
  new arrivals, colours, patterns, sizing, at product level and in aggregate.
  Covers the **most recent two years** via MCP, on fast infrastructure for
  real-time queries; the complete archive remains accessible through EDITED's
  API. Two complementary query tools: `market_data_options_search` (row-level
  products — "show me", "list", "cheapest") and `market_data_table` (aggregates
  and analytics — "how many", "average price", "share by retailer", trends),
  plus `market_data_entitlements` (which verticals this account can access, and
  its default) and `market_data_docs` (exact field / metric / operator reference,
  one topic per call).
- **Trend & Research** (`researchmcp`) — EDITED's editorial content: trend
  reports, runway analysis, seasonal commentary, market research, with image
  retrieval. Follow a **discovery → drill-down** pattern: `research_article_search`
  to find relevant reports, then `research_chunk_search` / `research_read_report`
  / `research_image_search` scoped by `report_ids`.
- **Messaging & Promotions** (`messagingmcp`) — retailer homepages and marketing
  emails captured at intervals (homepages and emails only, not category landing
  pages), exposed as two indexes meant to be queried together: `messaging_search`
  for the creative itself, and the promo tools
  (`count_promos`, `list_promos`, `aggregate_promos`, `search_promo_text`) for
  structured promotions. `enrich_with_vm` bridges the two.
- **Helpers** (`mdmcp`) — identifier resolution (`search_markets`,
  `search_retailers`, `search_brands`, `search_product_searches`,
  `search_size_group`, `search_size_options`) and data quality
  (`get_retailer_coverage`). A functional grouping, not a separate backend:
  these are Competitive Market Data tools and carry the `mdmcp-` prefix like
  the rest — the short names here drop the prefix for reading, but the wire name
  you pass to `tools/call` is the prefixed form (e.g. `mdmcp-search_retailers`).
  Called before or alongside the domain tools. The messaging domain resolves its
  own retailers with `messagingmcp-list_retailers`.

## Start here

- [EDITED MCP — home](/): what the server does and where to go next
- [Quickstart](/quickstart): from zero to a working call in four steps
- [The data](/the-data): what each domain contains and what you can do with it
- [How to query](/how-to-query): resolution, coverage, tool selection, and the
  server-defined prompts
- [Reference](/reference): the complete, always-current tool catalogue with
  schemas and a live "Try it" widget (generated per environment, so it always
  matches the tools your gateway exposes)

## Patterns worth knowing before you call a tool

- **Check coverage before analytics.** A clean aggregate from `market_data_table`
  can be silently wrong if a retailer had a data gap in the date range. Call
  `get_retailer_coverage` first for any time-windowed or period-over-period
  query. See [How to query → Coverage checking](/how-to-query#coverage-checking).
- **Omit `vertical` unless asked for another one.** The three verticals are
  `apparel`, `beauty`, `homeware` (note: `homeware`, not `home`). Omitted, it
  resolves to the account's default; requesting one the account isn't entitled
  to is an error, not an empty result — check with `market_data_entitlements`.
  Set it consistently across the tools in a workflow. See
  [How to query → Choosing a vertical](/how-to-query#choosing-a-vertical).
- **Options vs table.** If the user wants a *list of products*, use
  `market_data_options_search`; if they want a *number, percentage, or chart*,
  use `market_data_table`.
- **Discovery before drill-down (research).** Start with `research_article_search`;
  don't jump straight to paragraph search or a full report read. Optionally parse
  a relative window or topic up front with `research_analyze_query`.
- **Structured and visual together (messaging).** Count/aggregate promotions for
  the numbers, `list_promos` for examples, `messaging_search` / `enrich_with_vm`
  for the creative context behind them.
- **You don't need a model to call a tool.** MCP is a protocol — call a tool
  directly when you know which one and which arguments; reserve model-driven tool
  selection for cases that genuinely need runtime judgment. See
  [How to query → Calling a tool doesn't require a model](/how-to-query#calling-a-tool-doesnt-require-a-model).
- **Use the server-defined prompts.** One per domain —
  `mdmcp-market_data_query_guide`, `researchmcp-research_orchestration`, and
  `messagingmcp-messaging_orchestration` — encode EDITED's recommended routing
  and orchestration; compose them in rather than re-implementing the rules
  yourself. Fetch them with `prompts/get`; they update server-side without a
  redeploy.

## Concepts

- [What is MCP?](/concepts/what-is-mcp): the protocol and how it differs from a REST API
- [Tools](/concepts/tools), [Resources](/concepts/resources), [Prompts](/concepts/prompts): the three MCP primitives
- [Transports](/concepts/transports): how Streamable HTTP works here

## Recipes

- [Example workflow](/recipes/example-workflow): an end-to-end agentic flow — fuzzy question in, resolved ids out, data back
- [Connect Claude Desktop](/recipes/connect-claude-desktop), [Connect Claude Code](/recipes/connect-claude-code), [Connect a custom client](/recipes/connect-custom-client)
- [Using the Reference](/recipes/using-the-reference): try tools live in the browser

## Operations

- [Authentication & access](/operations/authentication): getting and sending your `x-api-key`
- [Errors](/operations/errors), [Rate limits](/operations/rate-limits), [Versioning](/operations/versioning)
- [Changelog](/changelog): surface changes to tools, parameters, resources, and prompts

## Full text

- [/llms-full.txt](/llms-full.txt): the complete rendered text of every page