Skip to main content

​
[1.2.0] - 2026-10-07

The v2beta MCP server (/v2beta/spark-api/mcp) now exposes ten tools.

​
Added

  • list_skills returns workflow skill keys and short descriptions. Hosts call it at the start of each new analysis.
  • get_skills returns the full markdown instructions for the skill keys you pass in skill_keys. Unknown or empty keys return isError: true.
  • explore_datasets returns short or verbose summaries for 1–5 dataset codes from list_datasets. A dataset whose summary is unavailable carries summary_error, and the other datasets still return.
  • explore_taxonomy returns the survey questions and attributes relevant to a topic, scoped by optional dataset_codes, enforced_audiences, location_codes, and wave_codes.

​
Notes

  • Existing tools and call order are unchanged. Clients that build calls from tools/list pick up the new tools automatically. See Overview for when to call each tool.

​
[1.1.0] - 2026-09-18

The v2beta MCP server (/v2beta/spark-api/mcp) is updated.

​
Added

  • MCP protocol version 2026-07-28 is now supported. New clients negotiate 2026-07-28 via the server/discover handshake; clients that use the legacy initialize handshake continue to negotiate down to 2025-11-25 and keep working unchanged.
  • tools/list responses now include SEP-2549 cache hints (ttlMs, cacheScope) so clients can cache the tool catalogue between calls.
  • Tool annotations always include idempotentHint and readOnlyHint (previously omitted when unset).

​
Changed

  • Breaking: generate_insights now takes a prompts array (1–10 per call) instead of a single prompt, and returns results[] 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 send prompts and read results[].

​
Added

  • Per-result failure isolation on generate_insights: when one prompt fails, its results[] entry carries message and error, and sibling successes are preserved. The tool call itself only returns isError: true for 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-Id is 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 ephemeral instant audiences, 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/mcp route on this channel)
  • global_filters tool for location and timeframe scope
  • audience_generation tool for creating audiences from natural language prompts
  • generate_insights tool for insight discovery

​
Changed

  • OpenAI / ChatGPT clients use the same endpoint and standard tool names as every other client
  • explore_insight is the follow-up enrichment tool for all clients and returns structured JSON
See the Transition guide for endpoint and tool mapping from earlier releases.

​
[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_audiences tool for searching saved/platform audiences by free-text query; optional dataset_codes, exclude_audience_ids, and limit (1–100)

​
Changed

  • chat_gwi / search: supports optional dataset_codes to 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 optional docked_audiences to scope insights to platform audience UUIDs (max 10; use IDs from search_audiences)
  • chat_gwi / search: when both dataset_code and dataset_codes are provided, dataset_codes takes precedence and dataset_code is ignored
  • chat_gwi / search: when both dataset_code and dataset_codes are omitted, the default dataset available to the user is used (previously hard-coded to ds-core)
  • list_datasets: returns hierarchical folders and nested dataset nodes so clients can identify valid root/child combinations
  • explore_insight_gwi / fetch: response now includes the origin datasets of the corresponding insight
  • explore_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 audience
  • fetch: response now includes structured metadata with an attributes array (question, answer, percentage, sample, universe_size, index) plus timeframe_groups, location_groups, audiences, and datasets for the source insight
  • search and fetch now return typed structured results instead of JSON encoded inside content text 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 optional limit to set the maximum number of insights returned per call (1–20; default 10)

​
[0.2.0] - 2026-03-11

​
Added

  • list_datasets tool for listing available GWI datasets; use to discover dataset codes for chat_gwi
  • chat_gwi: optional dataset_code argument to specify which dataset to query; default: ds-core

​
[0.1.0] - 2025-12-01

​
Added

  • chat_gwi tool for gathering insights about audiences based on GWI data
  • explore_insight_gwi for exploring detailed information about the insight statistics
  • OAuth2 support for secure authentication

​
Changed

  • Initial release of the Spark MCP