> ## 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

## \[0.5.0] - 2026-09-23

Both MCP servers are updated:

* **standard MCP** (`/v1/spark-api/mcp`)
* **ChatGPT MCP** (`/v1/spark-api/openai/mcp`)

### Added

* MCP protocol version `2026-07-28` is now supported on both endpoints. 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).

### Notes

* 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.

***

## \[0.4.1] - 2026-09-16

Both MCP servers are affected:

* **standard MCP** (`/v1/spark-api/mcp`)
* **ChatGPT MCP** (`/v1/spark-api/openai/mcp`)

### Changed

* The server no longer returns an `Mcp-Session-Id` header on `initialize`, and each JSON-RPC POST is handled independently. Clients should not send `Mcp-Session-Id` on subsequent requests and should not rely on server-side session continuity between calls. Continue to follow the standard MCP lifecycle (`initialize` → `notifications/initialized` → `tools/list` → `tools/call`) on every new connection.
* `chat_gwi` / `explore_insight_gwi` / `search` / `fetch`: tool descriptions and server instructions now guide host LLMs to follow a two-step flow for audience-size and universe questions (e.g. "how many people…", "audience size", "universe", "how big is…") instead of re-prompting the discovery tool for a headcount:
  * **Standard MCP:** call `chat_gwi` first to get the relevant insight, then call `explore_insight_gwi` with the returned `insight_id` to read the universe size and underlying stats.
  * **ChatGPT MCP:** call `search` first to get the relevant result, then call `fetch` with the returned `results[].id` to read `universe_size` and underlying stats.
* No changes to tool inputs, outputs, or transport behavior — existing clients continue to work; well-behaved host LLMs will start chaining the two calls automatically for universe-size questions.

### Fixed

* `list_datasets`: returns an empty array instead of an error when the caller has no dataset access. The REST `GET /v1/spark-api/datasets` endpoint now behaves the same way, responding with `HTTP 200` and an empty list.
* `search_audiences`: results now include only saved platform audiences (`authored`, `shared`, `curated`) and exclude ephemeral `instant` audiences, which previously dominated results

***

## \[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

***