[1.5.0] - 2026-11-18
Tool responses on/v2/spark-api/mcp now flag simulated data, and audience_generation limits the number of audiences per call.
Added
- Structured tool output includes
is_simulatedon each record that can use simulated data.truemeans that specific record uses simulated data:list_datasetsandrender_dataset_picker:is_simulatedon dataset nodes in thedatasetstree.search_audiencesandaudience_generation:is_simulatedon eachaudiences[]item.explore_datasets:is_simulatedon each returned dataset.explore_taxonomy:is_simulatedon each returned dataset, audience, question, and attribute.generate_insights:is_simulatedon eachresults[].insights[]item.explore_insight: top-levelis_simulatedfor the insight, plusis_simulatedon nestedmetadatarecords such asattributes,audiences, anddatasets.
- Server instructions and tool descriptions now tell host LLMs to place a
`[✦ Simulated]`marker immediately after the name of each simulated record they present. The marker applies only to the record whose own flag istrue. It is never inherited from a parent dataset or related audience.
Changed
audience_generationaccepts 1–10 audience descriptions inaudiences. Calls with more than 10 audiences, or with empty or whitespace-only entries, are rejected as invalid input before any audience is created.
Notes
- Existing clients that treat unknown fields as optional need no code changes.
- To create more than 10 audiences, split the request across multiple
audience_generationcalls. Calls with 10 or fewer audiences behave as before.
[1.4.0] - 2026-11-06
render_dataset_picker is now available on /v2/spark-api/mcp and /v2beta/spark-api/mcp.
Added
render_dataset_pickerlets users browse and choose datasets beforeglobal_filters. On hosts that support MCP Apps, the host renders an interactive dataset picker. On text-only hosts, the agent presents a short overview of the dataset catalog. Pass optionalaudiencesfor dataset compatibility checks andselected_datasetsto pre-fill the picker when re-opening it.
Notes
- Use
render_dataset_pickerwhen the user wants to browse or choose datasets, andlist_datasetswhen the user already named a dataset. Do not call both in the same dataset-selection step. See Overview for the full call order. - Clients that build calls from
tools/listpick up the new tool automatically.
[1.3.0] - 2026-11-04
Spark MCP v2 is now available at/v2/spark-api/mcp.
Added
- New endpoint:
POST https://api.globalwebindex.com/v2/spark-api/mcp. It exposes the same tools, tool descriptions, and call order as/v2beta/spark-api/mcp, and uses the same authorization.
Notes
/v2beta/spark-api/mcpremains available and unchanged. To move to v2, replace/v2beta/with/v2/in your MCP server URL. No other client changes are needed.
[1.2.0] - 2026-10-07
The v2 MCP server (/v2beta/spark-api/mcp) now exposes ten tools.
Added
list_skillsreturns workflow skill keys and short descriptions. Hosts call it at the start of each new analysis.get_skillsreturns the full markdown instructions for the skill keys you pass inskill_keys. Unknown or empty keys returnisError: true.explore_datasetsreturnsshortorverbosesummaries for 1–5 dataset codes fromlist_datasets. A dataset whose summary is unavailable carriessummary_error, and the other datasets still return.explore_taxonomyreturns the survey questions and attributes relevant to a topic, scoped by optionaldataset_codes,enforced_audiences,location_codes, andwave_codes.
Notes
- Existing tools and call order are unchanged. Clients that build calls from
tools/listpick up the new tools automatically. See Overview for when to call each tool.
[1.1.0] - 2026-09-18
The v2 MCP server (/v2beta/spark-api/mcp) is updated.
Added
- MCP protocol version
2026-07-28is now supported. New clients negotiate2026-07-28via theserver/discoverhandshake; clients that use the legacyinitializehandshake continue to negotiate down to2025-11-25and keep working unchanged. tools/listresponses now include SEP-2549 cache hints (ttlMs,cacheScope) so clients can cache the tool catalogue between calls.- Tool annotations always include
idempotentHintandreadOnlyHint(previously omitted when unset).
Changed
- Breaking:
generate_insightsnow takes apromptsarray (1–10 per call) instead of a singleprompt, and returnsresults[]with one entry per prompt in the same order. Downstream calls run concurrently, so hosts can batch related topics into one tool call. Update clients to sendpromptsand readresults[].
Added
- Per-result failure isolation on
generate_insights: when one prompt fails, itsresults[]entry carriesmessageanderror, and sibling successes are preserved. The tool call itself only returnsisError: truefor batch-wide failures such as validation errors or a missing referrer.
Notes
- Batch concurrency is capped server-side (default 5 concurrent downstream calls per request). Latency scales with the slowest prompt, so calls with many prompts can exceed 10 seconds.
- Transport remains stateless HTTP JSON-RPC: no
Mcp-Session-Idis issued or required, and every request stands on its own. - Existing clients that treat unknown fields as optional need no code changes.
[1.0.1] - 2026-08-19
Fixed
search_audiences: results now include only saved platform audiences (authored,shared,curated) and exclude ephemeralinstantaudiences, which previously dominated results
[1.0.0] - 2026-08-14
Added
- New channel:
/v2beta/spark-api/mcp— single MCP endpoint for all clients (no/openai/mcproute on this channel) global_filterstool for location and timeframe scopeaudience_generationtool for creating audiences from natural language promptsgenerate_insightstool for insight discovery
Changed
- OpenAI / ChatGPT clients use the same endpoint and standard tool names as every other client
explore_insightis the follow-up enrichment tool for all clients and returns structured JSON
[0.4.0] - 2026-07-15
Both MCP servers are updated:- standard MCP (
/v1/spark-api/mcp) - ChatGPT MCP (
/v1/spark-api/openai/mcp)
Added
search_audiencestool for searching saved/platform audiences by free-text query; optionaldataset_codes,exclude_audience_ids, andlimit(1–100)
Changed
chat_gwi/search: supports optionaldataset_codesto query a root dataset together with one or more of its add-on studies (values must belong to the same dataset tree)chat_gwi/search: supports optionaldocked_audiencesto scope insights to platform audience UUIDs (max 10; use IDs fromsearch_audiences)chat_gwi/search: when bothdataset_codeanddataset_codesare provided,dataset_codestakes precedence anddataset_codeis ignoredchat_gwi/search: when bothdataset_codeanddataset_codesare omitted, the default dataset available to the user is used (previously hard-coded tods-core)list_datasets: returns hierarchical folders and nested dataset nodes so clients can identify valid root/child combinationsexplore_insight_gwi/fetch: response now includes the origindatasetsof the corresponding insightexplore_insight_gwi: attribute output now includes Universe Size alongside question, answer, percentage, sample, and index — the estimated number of real-world internet users within the audiencefetch: response now includes structuredmetadatawith anattributesarray (question,answer,percentage,sample,universe_size,index) plustimeframe_groups,location_groups,audiences, anddatasetsfor the source insightsearchandfetchnow return typed structured results instead of JSON encoded insidecontenttext blocks; clients that already parse the tool result payload need no changes, but clients reading raw text MAY switch to the structured result
[0.3.0] - 2026-07-07
Both MCP servers are updated:- standard MCP (
/v1/spark-api/mcp) - ChatGPT MCP (
/v1/spark-api/openai/mcp)
Changed
chat_gwi/search: supports optionallimitto set the maximum number of insights returned per call (1–20; default 10)
[0.2.0] - 2026-03-11
Added
list_datasetstool for listing available GWI datasets; use to discover dataset codes forchat_gwichat_gwi: optionaldataset_codeargument to specify which dataset to query; default:ds-core
[0.1.0] - 2025-12-01
Added
chat_gwitool for gathering insights about audiences based on GWI dataexplore_insight_gwifor exploring detailed information about the insight statistics- OAuth2 support for secure authentication
Changed
- Initial release of the Spark MCP

