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

# Transition Guide

> Transition from Spark MCP v1 to v2beta

<Warning>
  **Beta.** `/v2beta/spark-api/mcp` is a preview endpoint, not the final v2 surface.
  An official frozen `/v2` will be published later from this channel — plan for a further
  URL update then. v1 remains available and is not deprecated.
</Warning>

## What you need to change

1. **URL** — point clients at the single v2beta endpoint (see mapping below).
2. **Tool names** — especially if you used the OpenAI profile (`search` / `fetch`).
3. **New tools** — adopt `global_filters` and `audience_generation` where relevant.

## Endpoint mapping

| Client type                 | v1                         | v2beta                  |
| :-------------------------- | :------------------------- | :---------------------- |
| Standard MCP clients        | `/v1/spark-api/mcp`        | `/v2beta/spark-api/mcp` |
| OpenAI / ChatGPT connectors | `/v1/spark-api/openai/mcp` | `/v2beta/spark-api/mcp` |

There is no separate OpenAI route on v2beta. OpenAI clients use the same URL and the same standard tool names as everyone else.

```text theme={null}
POST https://api.globalwebindex.com/v2beta/spark-api/mcp
```

## Tool mapping

| v1 standard           | v1 OpenAI          | v2beta                | Notes                                                                                  |
| :-------------------- | :----------------- | :-------------------- | :------------------------------------------------------------------------------------- |
| `chat_gwi`            | `search`           | `generate_insights`   | Discovery                                                                              |
| `explore_insight_gwi` | `fetch`            | `explore_insight`     | Follow-up enrichment; returns structured JSON; replaces OpenAI `fetch` on this channel |
| `list_datasets`       | `list_datasets`    | `list_datasets`       | Dataset discovery                                                                      |
| `search_audiences`    | `search_audiences` | `search_audiences`    | Find saved audiences                                                                   |
| —                     | —                  | `global_filters`      | Location / timeframe scope                                                             |
| —                     | —                  | `audience_generation` | Create audiences from prompts                                                          |

## Suggested migration checklist

1. Keep your v1 integration running.
2. Add or point a test connector / client at `/v2beta/spark-api/mcp` (ChatGPT uses this same URL — there is no `/openai/mcp` on v2beta).
3. If you hardcode tool names in a custom agent, replace `chat_gwi` / `search` with `generate_insights`, and `fetch` / `explore_insight_gwi` with `explore_insight`.
4. Always call `global_filters` before audience or insight tools on a new analysis. See [Overview](/docs/spark-mcp/v2beta/overview).
5. Use `search_audiences` or `audience_generation` when the request needs an audience; pass IDs into `generate_insights.enforced_audiences`.
6. Retest Claude, ChatGPT, and any custom agents against the single endpoint.

## What stays the same

* MCP lifecycle: `initialize` → `notifications/initialized` → `tools/list` → `tools/call`
* Authentication model (OAuth 2.0 and access tokens) — see [Authorization](/docs/spark-mcp/v2beta/getting-started/authorization)
* v1 remains available; existing dual routes are unchanged

## Related

* [Overview](/docs/spark-mcp/v2beta/overview)
* [Integration guide](/docs/spark-mcp/v2beta/integration-guide/overview)
* [Changelog](/docs/spark-mcp/v2beta/changelog)