> ## 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. # Execute GWI MCP tool calls > This endpoint handles MCP tool calls through JSON-RPC. Supported tools: **1. chat_gwi** - Query audience insights - Returns main response, insights with IDs, sources, and chat ID - Use for initial queries and follow-ups **2. explore_insight_gwi** - Get detailed statistics - Returns percentages, sample sizes, and index scores - Use with insight IDs from chat_gwi responses **3. list_datasets** - List available datasets - Used to get the dataset codes that can be passed to chat_gwi ## OpenAPI ````yaml post /v1/spark-api/mcp openapi: 3.0.0 info: title: GWI Spark API - MCP Server version: 1.0.0 description: > # GWI MCP Server for AI Assistants The GWI MCP (Model Context Protocol) server provides AI assistants with access to Global Web Index audience insights and market intelligence data. ## Available Tools ### 1. chat_gwi - Query Audience Insights **Purpose:** Get data on demographics, interests, digital behavior, and media preferences across global markets. **When to use:** - Initial queries about audience behavior or preferences - Questions about market insights - Demographic analysis requests - Digital behavior patterns **Example queries:** - "What marketing channels work best for Audi drivers in the US?" - "Tell me about Gen Z social media habits in Europe" - "What are the shopping preferences of millennials in Asia?" ### 2. explore_insight_gwi - Deep Dive into Insights **Purpose:** Get detailed breakdowns of specific insights returned by chat_gwi. **When to use:** - User asks for "more details" or "tell me more" about a specific insight - User wants to "expand on" or get "additional information" about something from chat_gwi ### 3. list_datasets - List Datasets **Purpose:** List all available GWI datasets (e.g. Core, USA). **When to use:** - To discover which dataset codes can be passed to chat_gwi through the dataset_code parameter ## Request/Response Format All requests use JSON-RPC 2.0 format: ### Request Structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "tools/call", "params": { "name": "tool_name", "arguments": { // tool-specific arguments } } } ``` ### Response Structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "result": { "content": [ { "type": "text", "text": "Formatted response with insights..." } ] } } ``` ### Tool errors (`result.isError`) **When to check** After a successful JSON-RPC envelope (HTTP **200**, no top-level `error` field), look at **`result.isError`**: | `result.isError` | Meaning | | --- | --- | | `true` | Tool failed. Read `result.content` — usually one `text` item with a human-readable message. | **Why HTTP can still be 200** A failed tool is still a completed JSON-RPC call. The failure is signaled in **`result`**, not by HTTP status alone. **Common reasons for `isError: true`** 1. **Invalid arguments** — bad or missing inputs before or during validation, for example: - `chat_gwi`: empty `prompt`; `chat_id` present but not a valid UUID - `explore_insight_gwi`: missing or invalid UUID `insight_id` - Other tools: same pattern where IDs or required strings are wrong 2. **Downstream / service errors** — GWI or infrastructure issues after arguments are accepted, for example: - Resource not found (chat, insight, dataset, etc.) - Timeouts, cancelled requests, or generic internal failures **`_meta.isInternalError`** When **`result._meta.isInternalError`** is **`true`**, the server classified the failure as internal or timeout-style. It may be omitted or `false` for validation or not-found style errors. **Not covered here: JSON-RPC protocol errors** Invalid `method`, malformed JSON-RPC, and similar issues use the standard JSON-RPC **`error`** field. They are **not** expressed as `result.isError`. ## Authentication Use Bearer token in Authorization header: ``` Authorization: Bearer YOUR_TOKEN ``` servers: - url: https://api.globalwebindex.com security: [] paths: /v1/spark-api/mcp: post: tags: - MCP Tools summary: Execute GWI MCP tool calls description: | This endpoint handles MCP tool calls through JSON-RPC. Supported tools: **1. chat_gwi** - Query audience insights - Returns main response, insights with IDs, sources, and chat ID - Use for initial queries and follow-ups **2. explore_insight_gwi** - Get detailed statistics - Returns percentages, sample sizes, and index scores - Use with insight IDs from chat_gwi responses **3. list_datasets** - List available datasets - Used to get the dataset codes that can be passed to chat_gwi operationId: mcpToolCall requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ChatGwiRequest' - $ref: '#/components/schemas/ExploreInsightGwiRequest' - $ref: '#/components/schemas/ListDatasetsRequest' description: JSON-RPC request for any supported MCP tool required: true responses: '200': description: > JSON-RPC response. HTTP 200 means the JSON-RPC call was processed, not that the tool succeeded. Inspect `result.isError` if present: - `true` — tool failed; the message is in `result.content[0].text`, and `result._meta.isInternalError` may be `true` for internal or timeout-style failures. See **Tool errors (`result.isError`)** in the overview above for full behavior. content: application/json: schema: $ref: '#/components/schemas/JsonRpcSuccessResponse' chat_gwi_response: examples: response: value: jsonrpc: '2.0' id: req-123 result: content: - type: text text: > # Data Analysis Result ## Main Response Based on GWI data, Audi drivers in the US show distinct preferences... Chat ID: 835aa1f0-cc30-4575-8829-557e03a29f76 ## Insights Each insight below is identified by a unique ID: - **Insight ID**: a1b2c3d4-e5f6-7890-abcd-ef1234567890 **Content**: 72% of Audi drivers prefer digital advertising channels - **Insight ID**: b2c3d4e5-f6a7-8901-bcde-f23456789012 **Content**: Social media engagement is 45% higher than average ## Sources **Topics**: Automotive, Digital Marketing **Datasets**: GWI Core (gwi_core) **Locations**: United States **Time periods**: Q4 2023 explore_insight_response: examples: response: value: jsonrpc: '2.0' id: req-456 result: content: - type: text text: > # Glossary for your understanding: Audience: the group of people participating in the survey Question: the question being asked Answer: the answer to the question Percentage: of the audience that selected this answer Sample: number of respondents from the audience Index: How likely it is for members of the audience to choose this answer compare to all internet users. Ex. 142 -> more, 90 -> less # Data to process Audience: Audi drivers in the United States ## Attributes ## Processing Instructions When responding to users about this data: 1. Reference specific insights by their IDs when relevant 2. Consider the source information for context 3. Note the time periods when discussing trends 4. If referring to specific datasets, include both the name and code if available explore_insight_gwi_success: examples: response: value: jsonrpc: '2.0' id: 2 result: content: - type: text text: > # Glossary for your understanding: Audience: the group of people participating in the survey Question: the question being asked Answer: the answer to the question Percentage: of the audience that selected this answer Sample: number of respondents from the audience Index: How likely it is for members of the audience to choose this answer compared to all internet users (100 is the average). Ex. 142 -> 42% more likely, 90 -> 10% less likely - Question: Which digital advertising channels do you engage with? - Answer: Search engine ads - Percentage: 68.50% - Sample: 1523 - Index: 132.00 # Responding guidelines - Present a summary of the audience - Present the question - For each answer, present the percentage, sample size and index and explain their meaning clearly tool_error_invalid_arguments: examples: response: value: jsonrpc: '2.0' id: req-validation-1 result: isError: true content: - type: text text: 'could not validate input: chat prompt is required' tool_error_internal: examples: response: value: jsonrpc: '2.0' id: req-internal-1 result: isError: true _meta: isInternalError: true content: - type: text text: something went wrong while processing request '401': description: Unauthorized - Invalid or missing bearer token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ChatGwiRequest: title: chat_gwi description: | Query audience insights: - Returns main response, insights with IDs, sources, and chat ID - Use for initial queries and follow-ups type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' description: JSON-RPC version id: type: string description: Unique request identifier example: req-123 method: type: string enum: - tools/call description: Method name for MCP tool calls params: type: object required: - name - arguments properties: name: type: string enum: - chat_gwi description: Tool name arguments: type: object required: - prompt properties: prompt: type: string description: >- Natural language question about audience behavior, preferences, or market insights. Be specific about the audience, market, or behavior you're interested in. example: >- What marketing channels work best for Audi drivers in the US? chat_id: type: string description: >- Optional. Include this to continue a previous conversation. Must be a valid UUID returned from a previous chat_gwi response; do not fabricate or reformat the value. pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: 835aa1f0-cc30-4575-8829-557e03a29f76 dataset_code: type: string description: | Optional. Dataset code fetched from list_datasets. example: ds-core default: ds-core example: jsonrpc: '2.0' id: req-123 method: tools/call params: name: chat_gwi arguments: prompt: What marketing channels work best for Audi drivers in the US? ExploreInsightGwiRequest: title: explore_insight_gwi description: | Get detailed statistics: - Returns percentages, sample sizes, and index scores - Use with insight IDs from chat_gwi responses type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' description: JSON-RPC version id: type: string description: Unique request identifier example: req-456 method: type: string enum: - tools/call description: Method name for MCP tool calls params: type: object required: - name - arguments properties: name: type: string enum: - explore_insight_gwi description: Tool name arguments: type: object required: - insight_id properties: insight_id: type: string description: > The unique identifier of an insight from a chat_gwi response. Must be a valid UUID that was returned in a previous chat_gwi call. This will return detailed statistics including: - Exact percentages for each answer - Sample sizes for statistical validity - Index scores (comparison to general population) pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 example: jsonrpc: '2.0' id: req-456 method: tools/call params: name: explore_insight_gwi arguments: insight_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 ListDatasetsRequest: title: list_datasets description: | List available datasets: - Used to get the dataset codes that can be passed to chat_gwi type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string method: type: string enum: - tools/call params: type: object required: - name properties: name: type: string enum: - list_datasets description: Tool name example: jsonrpc: '2.0' id: req-datasets-1 method: tools/call params: name: list_datasets JsonRpcSuccessResponse: type: object description: > JSON-RPC 2.0 success envelope for MCP `tools/call` (no top-level `error` field). When the tool fails, HTTP status is still typically **200** and this object is returned with `result.isError: true`. Use that flag rather than HTTP status alone. required: - jsonrpc - id - result properties: jsonrpc: type: string enum: - '2.0' id: type: string description: Request identifier echoed back result: type: object description: > MCP tool result. Inspect `isError` for tool-level success or failure. **`isError: true`** — the tool failed; `content` usually has one `text` item with a human-readable explanation. Typical causes: - **Invalid arguments** (e.g. empty `prompt`, invalid UUID for `chat_id` / `insight_id` where required). - **Downstream errors** (e.g. resource not found, timeout, cancelled request, or generic internal failure). **`_meta.isInternalError`** — when present and `true`, the server classified the failure as internal or timeout-style. Omitted or `false` for most validation and not-found style errors. This is **not** the same as a JSON-RPC protocol error: invalid `method` or malformed requests use the standard JSON-RPC `error` field instead of a tool `result`. required: - content properties: content: type: array items: type: object required: - type - text properties: type: type: string enum: - text text: type: string description: >- Tool response if successful. When `result.isError` is `true`, it is the error message (exact wording may vary; do not rely on it for branching except for documented validation cases). isError: type: boolean description: >- Tool-level failure indicator. `true` means the tool did not return a successful result; read `content[0].text` (when present) for details. Optional `_meta.isInternalError` refines internal failures. _meta: type: object description: Optional MCP result metadata. properties: isInternalError: type: boolean description: >- When `true`, indicates an internal or timeout-style failure path at the server. May be omitted for other error types. ErrorResponse: type: object properties: error: type: string example: unauthorized message: type: string example: Invalid or missing bearer token code: type: integer example: 401 securitySchemes: BearerAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer YOUR_TOKEN' ````