Skip to main content
Beta. /v2beta/spark-api/mcp is a preview endpoint, not the final v2 surface. An official frozen /v2 will be published later from this channel — plan for a further URL update then. v1 remains available and is not deprecated.
Spark MCP v2beta exposes six tools on one endpoint for every client:
There is no /openai/mcp route on this channel. OpenAI clients use the same URL and the same standard tool names. For request and response schemas with runnable examples, see API reference.

​
Call order

On each new analysis, tools run in this order. Always call global_filters, then generate_insights. Insert the other tools only when the conditions below apply.
1

1. list_datasets — when dataset scope is needed

Call if the user names a dataset, if a USA-specific request has no dataset chosen, or if USA vs Core is unclear (ask rather than guess). Use only codes this tool returns; pass them as dataset_codes downstream when selected.
2

2. global_filters — always

Resolve location and timeframe before any audience or insight tool. Forward non-empty location_codes and wave_codes to later tools. Never invent codes.
3

3. search_audiences — when the user names a saved audience

Prefer this when the user refers to an existing My / Shared / GWI audience by title. If nothing matches, fall back to audience_generation with that name as the prompt. Pass matched audiences[].id into generate_insights.enforced_audiences.
4

4. audience_generation — when the user describes a segment

Use when the user describes a cohort, interest, job, or behavior (not a saved title). Skip generic baselines such as “all internet users”. Pass location_codes / wave_codes from global_filters when present. Use returned audiences[].id in enforced_audiences.
5

5. generate_insights — always for insight questions

Primary discovery (replaces v1 chat_gwi / search). One focused topic per call. Pass enforced_audiences when you have audience IDs; forward non-empty location_codes / wave_codes; pass dataset_codes only if dataset scope was set earlier.
6

6. explore_insight — only on explicit drill-down

Replaces v1 explore_insight_gwi / fetch. Call only when the user asks for more detail on a specific insights[].id. Returns structured JSON (figures and provenance), not prose. Do not call automatically after discovery.
Never call search_audiences, audience_generation, or generate_insights before global_filters on a new analysis.

​
Tools at a glance

​
Example flow

  1. User asks: “Profile Gen Z skincare buyers in the UK and how to reach them.”
  2. global_filters with a location/timeframe-focused prompt (for example "UK").
  3. audience_generation for the cohort (or search_audiences first if they named a saved audience).
  4. generate_insights with a short topic prompt, enforced_audiences, and codes from global_filters.
  5. explore_insight only if the user picks a specific insight and asks for more detail.

​
Lifecycle

Follow the standard MCP lifecycle: initialize → notifications/initialized → tools/list → tools/call.