Skip to main content
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.

​
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

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

​
Tool mapping

​
Argument and response changes

v1 discovery tools take a single string prompt. v2beta generate_insights takes prompts[] (one or more short strings per call; see tools/list for limits). Read each prompt’s outcome from structuredContent.results[]. Soft failures for a single prompt appear on that result object (results[].error / results[].message), not only at the top level of structuredContent. Custom clients: build every tools/call payload from the tools/list input schemas for the tools you invoke — do not hardcode argument shapes from v1 or from these guides. See MCP Server integration guide.

​
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.
  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
  • v1 remains available; existing dual routes are unchanged