> ## Documentation Index
> Fetch the complete documentation index at: https://api.globalwebindex.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Version history and release notes for the Spark MCP Server

## \[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](https://api.globalwebindex.com/docs/spark-mcp/v2beta/overview.md) 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](https://api.globalwebindex.com/docs/spark-mcp/v2beta/transition-guide.md) 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