> ## 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.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_simulated` on each record that can use simulated data. `true` means that specific record uses simulated data:
  * `list_datasets` and `render_dataset_picker`: `is_simulated` on dataset nodes in the `datasets` tree.
  * `search_audiences` and `audience_generation`: `is_simulated` on each `audiences[]` item.
  * `explore_datasets`: `is_simulated` on each returned dataset.
  * `explore_taxonomy`: `is_simulated` on each returned dataset, audience, question, and attribute.
  * `generate_insights`: `is_simulated` on each `results[].insights[]` item.
  * `explore_insight`: top-level `is_simulated` for the insight, plus `is_simulated` on nested `metadata` records such as `attributes`, `audiences`, and `datasets`.
* 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 is `true`. It is never inherited from a parent dataset or related audience.

### Changed

* `audience_generation` accepts 1–10 audience descriptions in `audiences`. 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_generation` calls. 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_picker` lets users browse and choose datasets before `global_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 optional `audiences` for dataset compatibility checks and `selected_datasets` to pre-fill the picker when re-opening it.

### Notes

* Use `render_dataset_picker` when the user wants to browse or choose datasets, and `list_datasets` when the user already named a dataset. Do not call both in the same dataset-selection step. See [Overview](https://api.globalwebindex.com/docs/spark-mcp/v2/overview.md) for the full call order.
* Clients that build calls from `tools/list` pick 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](https://api.globalwebindex.com/docs/spark-mcp/v2/getting-started/authorization.md).

### Notes

* `/v2beta/spark-api/mcp` remains 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_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/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-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/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
