diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 195c25184..d8f8c1ec0 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -8,14 +8,17 @@ * link:{{navprefix}}/whats-new[What's New] ** link:{{navprefix}}/whats-new[New features] + *** link:{{navprefix}}/fixed-issues[Fixed issues] *** link:{{navprefix}}/known-issues[Known Issues] -** link:{{navprefix}}/embed-sdk-changelog[SDK and API changelog] +** link:{{navprefix}}/embed-sdk-changelog[SDK changelog] *** link:{{navprefix}}/embed-sdk-changelog[Visual Embed changelog] *** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] +** link:{{navprefix}}/rest-v2-changelog[REST API changelog] *** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] *** link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] +** link:{{navprefix}}/mcp-server-changelog[MCP Server changelog] ** link:{{navprefix}}/deprecated-features[Deprecation announcements] * Live Playgrounds @@ -225,14 +228,25 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/webhooks-lb-payload[Webhook response payload] *** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] -* MCP Servers and Tools -** link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] -*** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode] -*** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide] +* link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] +** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode] +** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide] + +* MCP Servers and tools ** link:{{navprefix}}/ai-analytics-integration[ThoughtSpot AI analytics integration] -*** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server] -*** link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to MCP clients] -*** link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom application or chatbot] +** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server] +*** link:{{navprefix}}/mcp-server-spotter3[MCP Server with Spotter 3] +*** link:{{navprefix}}/mcp-server-legacy[Legacy MCP Server architecture and tools] +** link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to MCP clients] +** link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom app] +** link:{{navprefix}}/mcp-tool-reference[MCP tool reference] +*** link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (Spotter 3)] +*** link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (legacy version)] +** link:{{navprefix}}/mcp-tool-reference[SDK components] +*** [.typedoc-Function]#link:{{navprefix}}/Function_startAutoMCPFrameRenderer[startAutoMCPFrameRenderer]# +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_AutoMCPFrameRendererViewConfig[AutoMCPFrameRendererViewConfig]# + + * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] diff --git a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc index fdf83129c..9f24f78e6 100644 --- a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc +++ b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc @@ -14,16 +14,11 @@ When integrated, the agent in your custom application can: * Support natural language conversation sessions for data questions. * Generate embeddable visualizations and programmatically create a Liveboard. -[IMPORTANT] -==== -Currently, the MCP Server integration does not support link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3 capabilities]. -==== - == Before you begin Before you begin, review the following prerequisites: * Node.js version 22 or later is installed and available in your environment. -* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release version. +* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. * Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required. == Authenticating users @@ -37,8 +32,16 @@ The token generated for the user session is used as a bearer token when your bac == Connecting clients If your custom chatbot implementation uses Claude, OpenAI, or Gemini LLM APIs to call MCP tools, ensure that your MCP Server endpoint, authentication token, and ThoughtSpot host are included in the API request. +When integrating with apps using custom workflows, ThoughtSpot recommends using the MCP server URL with the date-based `api-version` parameter. This allows you to pin a specific version and avoid introducing unintended changes to custom workflows that rely on tool responses. + +* For OAuth clients: +`https://agent.thoughtspot.app/mcp?api-version={YYYY-MM-DD}` + +* For bearer token clients: +`https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}` + === Claude MCP connector -If your application uses Claude MCP connector, use the following API request format to connect Claude to the MCP Server: +If your application uses the Claude MCP connector, use the following API request format to connect Claude to the MCP Server: [source,bash] ---- @@ -57,7 +60,7 @@ curl https://api.anthropic.com/v1/messages \ "mcp_servers": [ { "type": "url", - "url": "https://agent.thoughtspot.app/bearer/mcp", + "url": "https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}", "name": "thoughtspot", "authorization_token": "TS_AUTH_TOKEN@my-instance.thoughtspot.cloud" } @@ -68,10 +71,10 @@ curl https://api.anthropic.com/v1/messages \ In the above example, the API call includes: * The user’s message. -* ThoughtSpot’s MCP Server endpoint `https://agent.thoughtspot.app/bearer/mcp`. +* ThoughtSpot’s MCP Server endpoint `\https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}`. Replace `YYYY-MM-DD` with an actual date string. * An `authorization_token` that encodes which ThoughtSpot instance and user/token to use. -Claude uses the configured MCP Server to call ThoughtSpot MCP tools as needed, using the bearer-style token you provided. +Claude uses the configured MCP Server to call ThoughtSpot MCP tools as needed, using the bearer token you provided. === OpenAI Responses API If your application uses an OpenAI LLM, use the following API request format to connect OpenAI to the MCP Server: @@ -87,7 +90,7 @@ curl https://api.openai.com/v1/responses \ { "type": "mcp", "server_label": "thoughtspot", - "server_url": "https://agent.thoughtspot.app/bearer/mcp", + "server_url": "https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}", "headers": { "Authorization": "Bearer TS_AUTH_TOKEN", "x-ts-host": "my-instance.thoughtspot.cloud" @@ -101,10 +104,10 @@ curl https://api.openai.com/v1/responses \ In the above example, the API call includes the following parameters: * MCP as the tool type. -* ThoughtSpot MCP Server URL. +* ThoughtSpot MCP Server URL. Replace `YYYY-MM-DD` in the URL with an actual date string. * Authentication token and ThoughtSpot host URL. -The OpenAI LLM model uses the configured MCP Server, sends the provided headers on each MCP tool call, and gets the requested data from your ThoughtSpot instance under that token's identity. +The OpenAI LLM uses the configured MCP Server, sends the provided headers on each MCP tool call, and gets the requested data from your ThoughtSpot instance under that token's identity. === Gemini API @@ -120,7 +123,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const transport = new StreamableHTTPClientTransport( - new URL("https://agent.thoughtspot.app/bearer/mcp"), + new URL("https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}"), { requestInit: { headers: { @@ -154,7 +157,7 @@ await mcpClient.close(); The above example: -* Creates an MCP client and connects it to the ThoughtSpot MCP Server using `StreamableHTTPClientTransport`. +* Creates an MCP client and connects it to the ThoughtSpot MCP Server using `StreamableHTTPClientTransport`. Ensure that you replace `YYYY-MM-DD` in the URL with an actual date string. * Sends the required headers with the authentication token and ThoughtSpot host URL in MCP requests. * Wraps the MCP client as a tool and passes it into `GoogleGenAI` so Gemini can call ThoughtSpot tools as part of answering a user's query. @@ -163,17 +166,20 @@ The above example: To verify the integration: . Start a chat session by asking a question and verify whether your chatbot's LLM is calling the ThoughtSpot MCP tools to generate a response. + -A typical agentic workflow follows this pattern: -* Calls `getRelevantQuestions` to break the request into sub-queries -* Calls `getAnswer` to run those questions in ThoughtSpot and receive structured data and visualization metadata -* Based on a user prompt, calls `createLiveboard` to save the results in a ThoughtSpot Liveboard. -. Verify whether the metadata in the output includes `frame_url` to embed a visualization in an iframe or HTML snippet. +. Verify the tool calls. For information about tool calls and responses, see xref:mcp-tool-reference-guide.adoc[MCP tool reference guide]. +. Verify the Liveboard creation workflow and check whether a Liveboard is created in ThoughtSpot. +. Verify whether the metadata in the output includes the URL to embed a visualization in an iframe or HTML snippet. + +== Displaying visualization in iframe +Visualizations are returned as ThoughtSpot Answers via iframes. Use the xref:startAutoMCPFrameRenderer.adoc[startAutoMCPFrameRenderer] function to display the iframe. + +An example project showing how this is used in the `app.jsx` file with a code sample is available in the link:https://github.com/thoughtspot/developer-examples/blob/main/mcp/python-react-agent-simple-ui/client/src/App.jsx[developer-examples GitHub repository, window=_blank]. == Troubleshooting errors Cannot connect to MCP Server:: -* Verify if the MCP Server is reachable. +* Verify that the MCP Server is reachable. * Ensure that the correct MCP Server URL is used in API requests. * If the issue persists, verify the logs and contact ThoughtSpot Support for assistance. @@ -183,173 +189,13 @@ Authentication failure:: * Verify whether the MCP Server and ThoughtSpot host are reachable. * Verify whether the user has the necessary privileges to view data or create content. -== MCP tool calls and response output -The following sections outline the MCP request input schema and data structure of the response. - -=== ping -Runs a basic health check to validate that the MCP Server is reachable. - -[source,ts] ----- -const tsPing = await callMCPTool("ping", {}); ----- - -=== getDataSourceSuggestions -Suggests appropriate ThoughtSpot data models for a given natural language question. - - -==== Example request - -[source,ts] ----- -const dsSuggestions = await callMCPTool("getDataSourceSuggestions", { - query: "show me sales by region" // user's query -}); ----- - -==== Response format - -Returns an object containing an array of suggestions: - -[source,json] ----- -{ - "suggestions": [ - { - "header": { - "guid": "worksheet-guid-123", - "displayName": "Sales Analytics", - "description": "Sales performance by region, product, and channel" - }, - "confidence": 0.92, - "llmReasoning": "This worksheet contains sales metrics and regional dimensions relevant to the query." - } - ] -} ----- - -Key fields are: - -* `header.guid`: Unique ID for the datasource. The `datasourceId` is used in `getRelevantQuestions` and `getAnswer` calls. -* `header.displayName`: Name of the data source. -* `header.description`: Optional description of the data source. -* `confidence`: Numeric score indicating the confidence of the system about a data model being the right match for the user’s query. -* `llmReasoning`: LLM's reasoning for the suggestion. - -=== getRelevantQuestions -Uses ThoughtSpot’s reasoning engine to generate AI-suggested sub-queries that help generate specific answers for a given data context. - -==== Example call - -[source,ts] ----- -const result = await callMCPTool("getRelevantQuestions", { - query: "show me sales data", // User's natural language query - datasourceIds: ["model-guid-123"], // Array of worksheet/datasource GUIDs - additionalContext: "User is interested in the data for underperforming regions and products" -}); ----- - -==== Response example - -[source,json] ----- -{ - "questions": [ - "What is the total sales revenue by region?", - "Which products have the highest revenue?", - "What are the top selling categories?" - ] -} ----- - -Each returned question can then be passed individually into `getAnswer`. - -=== getAnswer -Executes a natural language question for a given data context and returns the resulting data and visualization metadata. Clients can use this data and frame URL to render visualizations. - -==== Example call - -[source,ts] ----- -const result = await callMCPTool("getAnswer", { - question: "Total sales by region", // Natural language question - datasourceId: "model-guid-123" // Worksheet/datasource GUID -}); ----- - -==== Response example - -[source,json] ----- -{ - "question": "Total sales by region", - "session_identifier": "abc-123-def-456", - "generation_number": 2, - "data": "\"Region\",\"Total Sales\"\n\"East\",100000\n...", - "frame_url": "https://...", - "fields_info": "..." -} ----- - -Key fields are: - -* `session_identifier`: Unique session ID used to group answers. Required when creating a Liveboard from this answer using the `createLiveboard` MCP tool. -* `generation_number`: Version number for this answer. Required for Liveboard creation. -* `question`: The executed question; useful for display and to pass it into the `createLiveboard` request. -* `data`: Data returned in encoded format. Contains column headers and all returned rows in comma-separated format, which can be parsed to render tables or charts in your application. -* `frame_url`: Optional iframe URL for embedding the visualization in your UI. -* `fields_info`: Descriptive metadata about the fields and chart, useful for explanations. - -=== createLiveboard - -Creates a ThoughtSpot Liveboard with one or more answers from the results. This is a two-step process and includes the following calls: - -. Call `getAnswer` to generate visualizations and obtain `session_identifier` and `generation_number`. -. Call `createLiveboard` with those values to create the Liveboard. - -==== Example call - -[source,ts] ----- -const answerData = JSON.parse(answerResult.result.content); - -const liveboardResult = await callMCPTool("createLiveboard", { - name: "My Sales Dashboard", - noteTile: "My Sales Dashboard was created by TS MCP Chat", // Description text for the Liveboard - answers: [{ - question: answerData.question, // Display name for the Liveboard - session_identifier: answerData.session_identifier, - generation_number: answerData.generation_number - }] -}); ----- - -Required attributes are: - -* `noteTile`: Use this field for any Liveboard description or notes; a separate description field is not supported. -* `answers`: Required array. Each item must include `question`, `session_identifier`, and `generation_number` from a prior `getAnswer` call. - -==== Response example - -[source,json] ----- -{ - "liveboardId": "liveboard-guid-here", - "name": "My Sales Dashboard", - "frame_url": "https://..." -} ----- - -Key fields are: +== MCP tools and response +For information about tool calls and responses, refer to the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide]. -* `liveboardId`: GUID of the created Liveboard. -* `name`: Name of the Liveboard. -* `frame_url`: URL that can be embedded to display the Liveboard. == Additional resources * To view the MCP Server code, go to the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. -* For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI]. +* For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI, window=_blank]. diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 19a630b1f..82424a00e 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,135 +6,182 @@ :page-pageid: mcp-integration :page-description: Learn what ThoughtSpot MCP Server is, when to use it, and how it fits into your AI and analytics architecture. -ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot MCP Server. +ThoughtSpot’s Model Context Protocol (MCP) Server enables integration of ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot MCP Server. == Overview -ThoughtSpot MCP Server exposes ThoughtSpot analytics as tools and resources that MCP-compatible agents can discover and call. - -When integrated, the MCP Server equips your AI agent/LLM with the following capabilities: +ThoughtSpot MCP Server exposes ThoughtSpot analytics as tools and resources that MCP-compatible agents can discover and use. When integrated, the MCP Server provides your AI agent or LLM with the following capabilities: * Automatic discovery of ThoughtSpot MCP tools * Natural language queries and responses * Programmatic creation of Liveboards and visualizations -* Generating embeddable visualizations for custom chatbot workflows +* Generating embeddable visualizations + +=== Supported integrations +ThoughtSpot MCP Server supports two primary integration options: + +[cols="2,6", options="header"] +|=== +| Integration option +| Description +| xref:mcp-server-client-connection.adoc[Plug-and-play clients] +|This integration works with agents or LLMs that natively support MCP, such as Claude, OpenAI, Gemini, or custom MCP clients. It allows your AI agent to call tools directly and leverage ThoughtSpot’s governed analytics, business semantic layer, data context, and row-level/object-level security, without the need to build your analytics logic. -=== Supported use cases +**When to use**: +If your application already has an AI chat interface or agentic experience, you can quickly add analytics to your existing setup without custom development. -ThoughtSpot supports MCP Server integration for the following use cases: +|xref:mcp-connect-custom-chatbot.adoc[Custom chatbot integration] +|If you are building your own MCP-based chatbot or application with custom orchestration logic or LLM, you can integrate the ThoughtSpot MCP Server to call ThoughtSpot tools behind your own web experience. -* *Plug-and-play clients* + -If your application already has an AI chat interface, you can use the MCP Server to plug ThoughtSpot analytics into your application's agentic experience. This integration works with agents or LLMs that natively support MCP, such as Claude, OpenAI, Gemini, or custom MCP clients. It allows your AI agent to call tools and leverage ThoughtSpot’s governed analytics, business semantic layer, data context, and row-level/object-level security, so you don’t need to build your own analytics logic. +**When to use**: +Use this option if your organization requires a custom conversation flow, backend orchestration, and a tailored analytics experience for your users. +|=== -* *Custom chatbot integration* + -If you are building an MCP-based chatbot or application with your own orchestration logic or LLM, and you want to call ThoughtSpot MCP tools behind a custom web experience, integrate the MCP Server into your application. This approach is recommended when you need fine-grained control over conversation flow, backend orchestration, and the analytics experience. +Regardless of integration mode, ThoughtSpot’s semantic layer, data context, and security features ensure trusted and governed analytics for all users. -==== Choosing the right integration option +=== MCP Server license +ThoughtSpot MCP Server is available as an add-on with the following link:https://www.thoughtspot.com/pricing[license plans]: -Your integration choice depends on where the conversational UI is presented to the user and whether your application relies on ThoughtSpot, a third-party AI agent, or your own agentic AI to orchestrate the analytics workflow. +* ThoughtSpot Enterprise Edition +* ThoughtSpot Embedded -Regardless of the integration mode, you can leverage ThoughtSpot’s semantic layer, data context, object-level, row-level, and column-level security to ensure trusted, governed analytics for your users. +To learn more about subscription options, contact your ThoughtSpot sales representative. -=== Architecture and roles -The MCP Server integration and orchestration layer includes the following core components: +== Core components and roles +The MCP Server integration and orchestration layers include the following core components: -[width="100%" cols="2,4"] +[width="100%" cols="2,6"] [options='header'] -|====== +|=== |Component|Role -|*Client Interface* a| -User interface that renders chat, responses, and charts. For example, Claude AI web app, Claude Desktop, ChatGPT, OpenAI-based integrations, Gemini-based agents, custom web applications, or internal tools. +|**Host application** | The AI platform or AI-native app that renders chat, responses, and charts, and manages user-facing conversation. For example, Claude AI web app, Claude Desktop, ChatGPT, OpenAI-based integrations, Gemini-based agents, custom web applications, or internal tools. -|*Agent or LLM* -a| Acts as orchestrator. + +|**MCP client** +a|The MCP client discovers available tools, manages the MCP connection to the server, and passes tool calls between the LLM and the MCP Server. -- Receives the user’s prompt -- Discovers ThoughtSpot MCP tools -- Decides which tools to call and in what order. -- Combines ThoughtSpot results with other sources and generates the final answer. +|**ThoughtSpot MCP Server** a| +The remote MCP server hosted by ThoughtSpot. -|*ThoughtSpot MCP Server* a| -- Acts as a gateway between the agent and ThoughtSpot. -- Exposes analytics as MCP tools. -- Validates requests and forwards calls to ThoughtSpot. +- Acts as a gateway between the MCP client and ThoughtSpot. +- Exposes ThoughtSpot analytics as MCP tools. +- Receives tool calls, authenticates via OAuth/Bearer Token, and routes requests to ThoughtSpot. -|*ThoughtSpot instance* +|**ThoughtSpot instance** | Your ThoughtSpot instance where data models, Liveboards, and security policies exist. + - Executes queries and generates visualizations -- Provides access to data - Enforces data security with RLS and CLS rules. -|*End user* -|Interacts with an AI client or custom application, asks questions, and acts on results. -|====== +- In integrations using the MCP Server with Spotter 3 support, it provides additional capabilities such as advanced analytics, reasoning, forecasting, automatic data source selection, and deep research. +|=== The following figure illustrates the interaction between the user, agent, and MCP Server: [.widthAuto] image::./images/agents-mcp-server-arch.png[MCP integration] -=== MCP tools and resources - -ThoughtSpot MCP Server exposes the following tools and resources: - -* `ping` + -Connectivity/health check. Used by the MCP host, such as Claude, Gemini, or ChatGPT, to verify whether it can reach the ThoughtSpot MCP Server and whether the server is available. - -* `getDataSourceSuggestions` + -Suggests the most relevant ThoughtSpot data sources for a given query. - -* `getRelevantQuestions` + -Uses ThoughtSpot’s reasoning engine to turn a broad or high‑level user query into a set of concrete analytical questions that should be asked of the data. - -* `getAnswer` + -Executes those analytical questions and returns structured data and answers. +== MCP Server architecture and tools +For more information about MCP tools, resources, and workflow processing, see the following documentation: -* `createLiveboard` + -Creates a ThoughtSpot Liveboard from a list of answers/questions, typically at the end of a conversation. It turns the conversational analysis into a Liveboard with visualizations. +* xref:mcp-server-spotter3.adoc[MCP Server with Spotter 3] +* xref:mcp-server-legacy.adoc[Legacy MCP Server architecture and tools] -=== How it works +//// -The agentic interactions in an orchestrated environment typically include these steps: +|**Embedded visualizations** +|Not supported in turnkey platforms; requires additional development work in custom apps. +|Supports direct embedding of charts in MCP clients and via `iframe_url` in custom apps. Every answer includes an `iframe_url` that renders as an interactive ThoughtSpot visualization. -. *User asks a question* + -A user sends a query in the chat interface to get data. For example, `What were the total sales of Jackets and Bags in the Northeast last year?`. + -Optionally, the user can specify the data context to generate a response. - -. *Agent calls `getDataSourceSuggestions` (optional)* + -If the user’s question doesn’t specify a data source, the agent can call `getDataSourceSuggestions`. -ThoughtSpot returns candidate data sources (models) with confidence scores and reasoning. - -. *User's query is decomposed into sub-questions* + -To break the user’s query into smaller analytical questions, the agent calls `getRelevantQuestions`. + -In response to the agent's request, ThoughtSpot returns the AI-suggested, schema-aware questions that are easier to execute analytically. - -. *The query is processed for generating answers* + -For each suggested or chosen question, the agent calls `getAnswer`. ThoughtSpot returns the following: + -* Preview data for LLM reasoning. -* Visualization metadata, including an embeddable `frame_url`. -* `session_identifier` and `generation_number` for charts that are used as input for creating a Liveboard. - -. *A Liveboard is generated from the results* (optional) + -The user can choose to save answers from the conversation in a ThoughtSpot Liveboard. For this workflow, the agent extracts `question`, `session_identifier`, and `generation_number` from each `getAnswer` response and calls `createLiveboard`. + -ThoughtSpot creates a Liveboard and returns identifiers and a `frame_url` for the Liveboard. -+ -During this interaction, users typically see a natural-language summary. When a Liveboard is created, a link to open the corresponding Liveboard in ThoughtSpot is generated. -+ -In custom applications, you can embed the visualizations generated from the interaction, load them inside iframe elements, and render interactive charts directly in your webpage. You can also add your own buttons or links, such as 'Save as Liveboard' or 'Pin this analysis', which call `createLiveboard` to create or persist a Liveboard that contains your current charts and analysis. - -== Getting access to the MCP Server - -ThoughtSpot MCP Server is available as an add-on with the following link:https://www.thoughtspot.com/pricing[license plans]: - -* ThoughtSpot Enterprise Edition -* ThoughtSpot Embedded - -To learn more about subscription options, contact your ThoughtSpot Sales representative. +=== MCP tools and resources +The following table +[cols="2,2,4", options="header"] +|=== +|| Legacy MCP Server setup | MCP Server with Spotter 3 support +|**MCP Server connectivity test**. | `ping` +| `check_system_readiness` + +|**Conversation session initiation** +|Does not support session-based architecture. Tools are stateless. +|`create_analysis_session` + +Creates a stateful session and returns `analytical_session_id`, which is required for subsequent calls. + +|**Data source selection** +|`getDataSourceSuggestions` + +Standalone tool. Called separately to retrieve source suggestions and pass +the result to other tools. +|Built into `create_analysis_session` via optional `data_source_id` parameter + +If the parameter is omitted, ThoughtSpot automatically selects the most relevant source from the question. + +|**Query submission** +|`getRelevantQuestions` + +Breaks a query into questions ThoughtSpot analytics can answer. Returns answers directly in the same call. +|`send_session_message` + +Sends a question or follow-up message in natural language. Does not return the full answer immediately, but triggers asynchronous processing. Returns only the `success` message. + +|**Intermediate thinking / reasoning** +|Not exposed to users. +|`get_session_updates` update types expose `text` and `text-chunk` to users during polling. + +|**Answer retrieval** +|`getAnswer` + +Returns structured data and answers and the full response. +|`get_session_updates` + +Polls for streamed updates across multiple calls and accumulates updates from every poll. The tool is called in a loop until the `is_done: true` state. + +|**Visualization output** +|Not included in tool responses +|The `iframe_url` field in the `session_update` -> `answer` -> `type` returned by the `get_session_updates` tool. + +|**Liveboard creation** +|`createLiveboard` + +Creates a Liveboard from a list of answers. +|`create_dashboard` + +Creates a dashboard from `answer_id` values collected from the session update type `answer`. Requires a `note_tile` HTML summary tile. + +|**Follow-up questions** +|`getRelevantQuestions` with `additionalContext` parameter. Requires prior context for each follow-up call. +|`send_session_message` with the same `analytical_session_id`. The session retains context automatically. The `additional_context` parameter can be included to inject new context for each follow-up question or message. +|| +|=== +//// + +== MCP Server URL + +ThoughtSpot MCP Server now uses date-based API versioning in the URL. New versions are identified using the `?api-version=YYYY-MM-DD` parameter, which you can append to the MCP Server URL to pin your integration to a specific version. Each new version may introduce tool changes, enhancements, or bug fixes. + +When you set the `api-version` to a specific date string, the server returns the version released on the specified date. If no new version of MCP Server is released on the date specified in the URL, the server returns the closest earlier version. For example, if you request `?api-version=2026-06-01` and no new version has been released since `2026-05-01`, the server returns the 2026-05-01 version. This means your integration continues to work without breaking, and you only need to update your pinned date if you want to opt in for a newer version. + +To automatically receive every new version of the MCP tools as ThoughtSpot releases them, use the URL without a pinned `api-version`. Note that the new versions may introduce changes to tool behavior, input parameters, or output schemas that affect your integration. Therefore, we recommend pinning your integration to a specific version. + +[cols="2,6", options="header"] +|==== +|Apps/Integration type| MCP Server URL +|**OAuth apps** + +(Plug-and-play integration) a| + +* `\https://agent.thoughtspot.app/mcp?api-version=latest` + +Always points to the latest version. + +* `\https://agent.thoughtspot.app/mcp` + +Currently, this URL points to the baseline version with legacy MCP tools. It will resolve to the latest version in the near future. + +* If you want to pin a specific version, use the URL with the `api-version` parameter and specify the date string: + +`\https://agent.thoughtspot.app/mcp?api-version={YYYY-MM-DD}`. For example, `?api-version=2026-05-01` + +|**Bearer token apps** a| * `\https://agent.thoughtspot.app/token/mcp` + +Always points to the latest version. +* `\https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}` + +Replace `{YYYY-MM-DD}` with the actual date string to point to the specified version or the closest earlier version. For example, `?api-version=2026-05-01` +|==== + +[IMPORTANT] +==== +The `\https://agent.thoughtspot.app/openai/mcp` and `\https://agent.thoughtspot.app/bearer/mcp` are deprecated and point to the version with legacy MCP tools only. +ThoughtSpot recommends migrating your existing MCP Server integration setup to the new version. For more information, see xref:mcp-server-changelog.adoc#_migration_guidelines[MCP Server changelog]. +==== == Next steps -* To learn how to connect existing MCP-aware tools such as Claude, ChatGPT, and Gemini, see xref:mcp-server-client-connection.adoc[Connecting MCP clients to ThoughtSpot MCP Server]. -* To learn how to integrate MCP Server with a custom chatbot or application, see xref:mcp-connect-custom-chatbot.adoc[Integrating MCP Server in a custom chatbot]. +* To learn how to connect existing MCP-aware tools such as Claude, ChatGPT, and Gemini, see the xref:mcp-server-client-connection.adoc[Connecting MCP clients to ThoughtSpot MCP Server] documentation. +* To learn how to integrate MCP Server with a custom chatbot or application, see the xref:mcp-connect-custom-chatbot.adoc[Integrating MCP Server in a custom chatbot] documentation. == Additional resources -* For information about MCP, see link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. -* For implementation details, see link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. +* For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. +* For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc new file mode 100644 index 000000000..78186247f --- /dev/null +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -0,0 +1,110 @@ += ThoughtSpot MCP Server changelog +:toc: true +:toclevels: 2 + +:page-title: MCP Server Changelog +:page-pageid: mcp-server-changelog +:page-description: Release history for the ThoughtSpot MCP Server, including new tools, breaking changes, deprecations, and bug fixes. +:keywords: MCP Server, changelog, release notes, api-version, breaking changes, deprecation + +This changelog lists the new features, enhancements, and other changes introduced in the released versions of the ThoughtSpot MCP Server. For information about MCP Server integration, see the xref:mcp-integration.adoc[MCP Server integration guide]. + +// ============================================================ +// VERSION TEMPLATE — copy this block for each new release +// ============================================================ +// +// == YYYY-MM-DD +// [.version-badge.breaking]#Breaking# / +// [.version-badge.new]#New# / +// [.version-badge.deprecated]#Deprecated# / +// [.version-badge.fixed]#Fixed# +// +// *API version string:* `?api-version=YYYY-MM-DD` +// *Status:* Current / Supported / Deprecated +// *Affects:* Developers, Administrators, End Users +// ============================================================ + + +== May 2026 + +*API version string:* `?api-version=2026-05-01`. + +*Upgrade notes*: Recommended for new integrations. Introduces breaking changes to existing MCP Server integrations. See the xref:mcp-server-changelog.adoc#_migration_guidelines[migration guidelines]. + +[.cl-table, cols="1,4", frame=none, grid=none] +|==== +a| +[.cl-label] +*2026-05-01* + +a| + +[discrete] +==== Support for Spotter 3 +ThoughtSpot MCP Server now supports Spotter 3, enabling advanced analytics, forecasting, multi-step reasoning, and deep research. The new MCP tools support real-time streaming, session-based conversations, and richer interactions. + +For more information, see xref:mcp-server-spotter3.adoc[MCP Server with Spotter 3]. + +--- + +[discrete] +==== MCP Server URL changes and API versioning [.version-badge.breaking]#Breaking# +MCP Server URLs now support date-based versioning, defined using the `?api-version=YYYY-MM-DD` parameter. Ensure that you update the xref:mcp-integration.adoc#_mcp_server_url[MCP Server URL] in your integrations as needed. + +[NOTE] +==== +* If the API version is set to a specific date, the server returns the latest version released on or before that date. +* If your integration has custom workflows that rely on MCP tools, pin it to a tested version using the `?api-version={YYYY-MM-DD}` parameter. +==== + +--- + +[discrete] +==== MCP tools and processing model [.version-badge.breaking]#Breaking# +The MCP Server URL now points to the Spotter 3-powered MCP tools. With this enhancement, the legacy tools in your existing integrations will be replaced with new tools. If your app uses custom workflows, you must update your integrations to use the new MCP tools or pin a previous version using the `?api-version={YYYY-MM-DD}` parameter in the URL to preserve your existing changes. + +===== Migration guidelines +Migrating from your existing setup to the new version requires updating the MCP client configuration to point to the new URL and rewriting tool-calling logic to use the new asynchronous, polling model. + +To update your integration to use Spotter 3 features and the new MCP tools: + +. Rewrite your integration to use the new tools. Replace the old synchronous tool-calling pattern with the new asynchronous polling pattern. For code samples and tool reference, see the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide]. +. Configure the URL that points to the new MCP tools. +. Test your integration end-to-end. +. Roll out to production environments after validation. +|==== + +== April 2026 +*API version string:* `?api-version=2026-04-30` or an earlier date string + +*Upgrade notes*: Supports the legacy MCP tools and URLs only. Upgrade your integrations to version 2026-04-30 or later. + +[.cl-table, cols="1,4", frame=none, grid=none] +|==== +a| +[.cl-label] +*2026-04-30* + +a| + +[discrete] +==== MCP tools, processing model, and answer retrieval +Supports the following MCP tools released in the initial version of ThoughtSpot MCP Server. + +* `ping`: Tests connectivity and authentication. +* `getDataSourceSuggestions`: Returns available data source suggestions +for a given query. +* `getRelevantQuestions`: Breaks a query into sub-questions. Returns answers synchronously. +* `getAnswer`: Returns the answer to a specific sub-question. +* `createLiveboard`: Creates a ThoughtSpot Liveboard from a list of answers. + +--- + +[discrete] +==== MCP Server URLs +Supports the following URLs: + +* `\https://agent.thoughtspot.app/mcp` (OAuth Apps) +* `\https://agent.thoughtspot.app/bearer/mcp` (Bearer Token Apps) +* `\https://agent.thoughtspot.app/openai/mcp` (OpenAI-compatible clients) + +These URLs are deprecated as of the MCP Server 2026-05-01 release. See the xref:mcp-server-changelog.adoc#_mcp_server_url_changes_and_api_versioning[changelog] for more information. + +|==== diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index 94dcb6281..748c30855 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -17,32 +17,63 @@ When your MCP client is connected to the ThoughtSpot MCP Server, the AI agent/LL * Create a Liveboard with the visualizations generated during the interaction. +//// [IMPORTANT] ==== * Currently, the MCP Server integration does not support link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3 capabilities]. * In the plug-and-play integration mode, embedding visualizations is not supported. ==== +//// == Before you begin Before you begin, review the following prerequisites: -* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release version. +* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. * Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required. === Connecting clients that support remote MCP servers -To connect to a client that supports remote MCP servers natively, add the MCP Server endpoint to your client's configuration settings. +To connect a client that supports remote MCP servers natively, add the MCP Server endpoint to your client's configuration settings. -`\https://agent.thoughtspot.app/mcp` +For OAuth clients, the following options are available: -For clients that require a bearer token for authentication, use the following URL format: +* `\https://agent.thoughtspot.app/mcp?api-version=latest` + +This URL always points to the latest version. -`\https://agent.thoughtspot.app/bearer/mcp` +* `\https://agent.thoughtspot.app/mcp` ++ +[NOTE] +==== +Currently, this URL points to the baseline version with legacy MCP tools. It will resolve to the latest version in the near future. During this period, you can switch to `\https://agent.thoughtspot.app/mcp?api-version=latest` to access the latest MCP tools. +==== + +* `\https://agent.thoughtspot.app/mcp?api-version={YYYY-MM-DD}` + +If you want to pin a specific version, use this URL format. + + +[IMPORTANT] +==== +The `\https://agent.thoughtspot.app/openai/mcp` is deprecated and not recommended for use in OpenAI integrations. +==== +//// +For bearer token clients:: +For clients that require a bearer token for authentication, use the following URL: ++ +`\https://agent.thoughtspot.app/token/mcp` (Recommended) + +This URL always points to the version with the latest tools. -For OpenAI MCP and Responses API integration, use the following URL: ++ +If you want to use a version released on or before a specific date, use the URL with the date parameter: + +`\https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}` -`\https://agent.thoughtspot.app/openai/mcp` -For additional information about how to register a remote MCP Server, refer to your client's documentation. +For OpenAI MCP and Responses API:: +Use the following URL: ++ +`\https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}` ++ +//// + +For more information about how to register a remote MCP Server, see your client's documentation. === Connecting MCP Server to local MCP clients For MCP clients that do not natively support configuring a remote MCP Server URL, you must use the `mcp-remote` component. For desktop clients that rely on local MCP components, ensure that Node.js version 22 or later is installed on your system. @@ -55,7 +86,7 @@ For MCP clients that do not natively support configuring a remote MCP Server URL "command": "npx", "args": [ "mcp-remote", - "https://agent.thoughtspot.app/mcp" + "https://agent.thoughtspot.app/mcp?api-version={YYYY-MM-DD}" // replace YYYY-MM-DD with an actual date string ] } } @@ -87,14 +118,14 @@ After the MCP Server is connected, some clients show *ThoughtSpot Data Sources* To verify the integration: . Start a chat session with the agent and verify the response. -. Verify that xref:mcp-integration.adoc#_mcp_tools_and_resources[MCP tools are being called] to generate responses. -. Prompt the agent to create a Liveboard from a query response and verify whether a Liveboard is added to your ThoughtSpot application. +. Verify that MCP tools are being called to generate responses. See the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide] for information about tool calls. +. Try the Liveboard creation request and verify whether a Liveboard is added to your ThoughtSpot application. == Troubleshooting errors MCP Server is not connected:: -* Verify if the MCP Server is reachable. +* Verify that the MCP Server is reachable. * Ensure that you have access to a ThoughtSpot instance. * Ensure that there are no configuration errors. * If the issue persists, verify the logs and contact ThoughtSpot Support for assistance. @@ -102,7 +133,7 @@ MCP Server is not connected:: Authentication failure:: If user authentication fails, or if the server returns HTTP 500, 401, or 403 status codes: * Verify whether the MCP Server endpoint and ThoughtSpot host are correctly configured in your client and are reachable. -* Verify if the user session has expired. Log in to your ThoughtSpot application to start a new session. +* Check whether the user session has expired. Log in to your ThoughtSpot application to start a new session. * Verify whether the user has the necessary privileges to view data or create content. == Additional resources diff --git a/modules/ROOT/pages/mcp-server-legacy.adoc b/modules/ROOT/pages/mcp-server-legacy.adoc new file mode 100644 index 000000000..d10e0fbfd --- /dev/null +++ b/modules/ROOT/pages/mcp-server-legacy.adoc @@ -0,0 +1,61 @@ += Legacy MCP Server architecture and tools +:toc: true +:toclevels: 3 + +:page-title: Legacy MCP Server architecture and tools +:page-pageid: mcp-server-legacy +:page-description: Learn about the legacy MCP Server architecture and how it fits into your AI and analytics architecture. + +The legacy MCP server setup uses synchronous architecture. It does not support advanced analytics, session context retention, automatic data source selection, streaming responses, and the full answer is always returned inline. All context and data source management must be handled by the client on every request. + +Functional capabilities:: +Limited capabilities for complex analysis and context integration. +When to use:: +It is recommended only for maintaining existing integrations, not for new development or advanced use cases. +Integration pattern and session model:: +The integration pattern is synchronous and stateless. Each tool call is independent and there is no persistent session. Any required context must be manually injected with every follow-up call, as the server does not retain context between requests. + +Data source selection:: +Data source suggestions are not built-in. A separate tool call (`getDataSourceSuggestions`) is required to retrieve possible data sources for each query. + +Response delivery:: +The server returns the full response in a single, synchronous call. There is no support for streaming or incremental updates. + +Follow-up questions:: +Every follow-up call requires the prior context to be manually included, as the server does not maintain conversational state. + +[.widthAuto] +image::./images/mcp-architecture-legacy.png[MCP architecture legacy] + +== Tool calls and workflow processing +The workflow in the legacy MCP Server setup typically includes the following stages: + +. *User asks a question* + +A user sends a query in the chat interface to get data. For example, `What were the total sales of Jackets and Bags in the Northeast last year?` + +Optionally, the user can specify the data context to generate a response. + +. *Agent calls `getDataSourceSuggestions` (optional)* + +If the user’s question doesn’t specify a data source, the agent can call `getDataSourceSuggestions` to retrieve a list of relevant ThoughtSpot data sources. +ThoughtSpot returns candidate data sources (models) with confidence scores and reasoning. + +. *User's query is decomposed into sub-questions* + +To break the user’s query into sub-questions, the agent calls `getRelevantQuestions`. ThoughtSpot returns the AI-suggested, schema-aware questions that are easier to execute analytically. + +. *The query is processed for generating answers* + +For each suggested or chosen question, the agent calls `getAnswer`. ThoughtSpot returns the following: + +* Preview data for LLM reasoning. +* Visualization metadata, including an embeddable `frame_url`. +* `session_identifier` and `generation_number` for charts that are used as input for creating a Liveboard. + +. *A Liveboard is generated from the results* (optional) + +To save answers from the conversation sessions in a ThoughtSpot Liveboard, the agent extracts the `question`, `session_identifier`, and `generation_number` from each `getAnswer` response and calls `createLiveboard`. + +ThoughtSpot creates a persistent Liveboard from the session's answers and returns identifiers and a `frame_url` for the Liveboard. + +In the legacy MCP Server setup, to ask a follow-up question, the agent calls the `getRelevantQuestions` again, because the server doesn't retain context. For follow-up questions, the agent must pass the context explicitly via `additionalContext`. + +For more information about the tool calls, input parameters, and response output, see xref:mcp-tool-reference-guide.adoc#_legacy_mcp_server_setup[MCP tool reference guide]. + + +== Additional resources +* For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. +* For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-server-spotter3.adoc b/modules/ROOT/pages/mcp-server-spotter3.adoc new file mode 100644 index 000000000..aaa0ae0d7 --- /dev/null +++ b/modules/ROOT/pages/mcp-server-spotter3.adoc @@ -0,0 +1,94 @@ += MCP Server with Spotter 3 capabilities +:toc: true +:toclevels: 3 + +:page-title: MCP Server with Spotter 3 capabilities +:page-pageid: mcp-server-spotter3 +:page-description: Learn about the MCP Server with Spotter 3 capabilities, including advanced analytics, streaming responses, and session-based conversations. + +ThoughtSpot MCP Server supports link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3, window=_blank], which enables advanced analytics, forecasting, multi-step reasoning and analysis, and deep research capabilities. +The MCP Server with Spotter 3 introduces new MCP tools, real-time streaming responses, session-based conversations, and richer interactions. + +[cols="2,4,4", options="header"] +|==== +||Legacy MCP Server setup|MCP Server with Spotter 3 +|**Functional differences** +|Limited capabilities for complex analysis and context integration. +a|* Supports advanced analytics, forecasting, and deep research capabilities. +* Supports asynchronous streaming, session-based conversations, and context integration. + +|**Recommended for** +|Maintaining existing integrations only. +|All new integrations + +|**Integration pattern + +Session model + +Response processing** +|Synchronous and stateless integration pattern. Each tool call is independent. Does not support persistent sessions and requires prior context to be injected manually on every follow-up call. + +|Asynchronous and stateful sessions. Allows multiple follow-up questions within a session. Responses are streamed with intermediate updates, including thinking narration and clarifications. Context is retained automatically across all follow-up questions within the session. + +|**Data source selection** +|Requires a separate tool call (`getDataSourceSuggestions`) to retrieve source suggestions. +|Built into session creation. If the `data_source_id` is not explicitly specified in the query, the most relevant source is automatically selected based on the user's query. + +|**Response delivery** +|Returns full response in a single synchronous call. +|Responses are streamed incrementally; updates are accumulated via polling. + +|**Follow-up questions** +|Requires prior context on every follow-up call. +|The session retains context automatically. + +Optionally, the `additional_context` parameter can be included to inject new external context for each follow-up question or message. + +|**API versioning support** +|Not available. +|Supports date-based API versioning, which is identified in the MCP Server URL as `?api-version=YYYY-MM-DD`. +|| +|==== + +The following figure illustrates the MCP architecture, tool calls, and workflow in the new MCP Server version: + +[.widthAuto] +image::./images/mcp-architecture-new.png[MCP architecture new] + +== Tool calls and workflow processing +The workflow in the MCP Server with Spotter 3 typically includes the following stages: + +1. *User asks a question* + +A user sends a query in the chat interface to get data insights. For +example, _What were the total sales of Jackets and Bags in the Northeast +last year?_ + +2. *Agent calls `create_analysis_session`* + +The agent calls `create_analysis_session` to establish a stateful analytical session with ThoughtSpot's Spotter 3 engine. ThoughtSpot returns an `analytical_session_id` that identifies the session for all subsequent calls. + +If the user specified a data source, the agent passes it as the optional `data_source_id` parameter. If not specified, ThoughtSpot automatically selects the most relevant data source based on the question. + +3. *Agent calls `send_session_message`* + +The agent calls `send_session_message` with the `analytical_session_id` and the user's question. Optionally, the agent can pass `additional_context` to provide external information that should influence the analysis. For example, `The user's fiscal year starts in April` or `The user is a manager of the West region`. + +ThoughtSpot confirms receipt with a `success` response and begins processing the question asynchronously. The answer is not returned in this call. + +4. *Agent polls `get_session_updates` for results* + +The agent calls `get_session_updates` repeatedly in a loop until `is_done` is `true`. ThoughtSpot streams updates incrementally across multiple polls. The agent must accumulate updates from every poll. ThoughtSpot returns the following update types: + +* `text-chunk` - real-time thinking narration from Spotter describing what it is doing, streamed in fragments. Concatenate chunks in order to form the complete narration. +* `text` - complete standalone messages representing clarifications, caveats, or assumptions Spotter made during analysis. +* `answer` - a final analytical result containing: +** `answer_title` - a human-readable description of what the answer shows. +** `answer_query` - the ThoughtSpot search query used to generate the answer. +** `iframe_url` - an embeddable URL for rendering an interactive ThoughtSpot visualization. +** `answer_id` - a unique identifier for the answer, used as input for creating a dashboard. + +5. *A dashboard is generated from the results (optional)* + +The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. + +ThoughtSpot creates a dashboard and returns a `dashboard_id` and a +`dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. + +6. *User asks a follow-up question (optional)* + +The user can ask a follow-up question in the same session. The agent calls `send_session_message` again using the same `analytical_session_id`. ThoughtSpot retains the full conversation context automatically. The agent returns to step 4 to poll for the follow-up response. + +For more information about the tool calls, input parameters, and response output, see xref:mcp-tool-reference-spotter3.adoc[MCP tool reference (Spotter 3)]. + +== Additional resources +* For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. +* For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-tool-reference-guide.adoc b/modules/ROOT/pages/mcp-tool-reference-guide.adoc new file mode 100644 index 000000000..90f34f4f4 --- /dev/null +++ b/modules/ROOT/pages/mcp-tool-reference-guide.adoc @@ -0,0 +1,21 @@ += MCP tool reference +:toc: true +:toclevels: 3 + +:page-title: ThoughtSpot MCP tool reference guide +:page-pageid: mcp-tool-reference +:page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. + +ThoughtSpot MCP Server provides specialized tools that enable the AI agent in your application to access ThoughtSpot analytics. This page lists all supported MCP tools and describes how to call these tools and analyze responses. Refer to the following sections for more information: + +* xref:mcp-tool-reference-spotter3.adoc[MCP Server version with Spotter 3] [.version-badge.new]#New# +* xref:mcp-tool-reference-legacy.adoc[MCP Server with legacy tools] + +== Additional resources + +* To view the MCP Server code, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. +* For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI]. +* See xref:mcp-connect-custom-chatbot.adoc[Integrating MCP Server in a custom application or chatbot] + + + diff --git a/modules/ROOT/pages/mcp-tool-reference-legacy.adoc b/modules/ROOT/pages/mcp-tool-reference-legacy.adoc new file mode 100644 index 000000000..f2a98be63 --- /dev/null +++ b/modules/ROOT/pages/mcp-tool-reference-legacy.adoc @@ -0,0 +1,173 @@ += MCP tool reference (legacy version) +:toc: true +:toclevels: 3 + +:page-title: ThoughtSpot MCP tool reference guide +:page-pageid: mcp-tool-reference-legacy +:page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. + +This reference guide lists the legacy MCP tools supported by the MCP Server in versions prior to 2026-05-01 and describes the MCP request input schema and data structure of the response. + +== ping +Runs a basic health check to validate that the MCP Server is reachable. + +[source,typescript] +---- +const tsPing = await callMCPTool("ping", {}); +---- + +== getDataSourceSuggestions +Suggests appropriate ThoughtSpot data models for a given natural language question. + +=== Example call + +[source,typescript] +---- +const dsSuggestions = await callMCPTool("getDataSourceSuggestions", { + query: "show me sales by region" // user's query +}); +---- + +=== Response + +Returns an object containing an array of suggestions: + +[source,json] +---- +{ + "suggestions": [ + { + "header": { + "guid": "worksheet-guid-123", + "displayName": "Sales Analytics", + "description": "Sales performance by region, product, and channel" + }, + "confidence": 0.92, + "llmReasoning": "This worksheet contains sales metrics and regional dimensions relevant to the query." + } + ] +} +---- + +Key fields are: + +* `header.guid`: Unique ID for the datasource. The `datasourceId` is used in `getRelevantQuestions` and `getAnswer` calls. +* `header.displayName`: Name of the data source. +* `header.description`: Optional description of the data source. +* `confidence`: Numeric score indicating the confidence of the system about a data model being the right match for the user’s query. +* `llmReasoning`: LLM's reasoning for the suggestion. + +== getRelevantQuestions +Uses ThoughtSpot’s reasoning engine to generate AI-suggested sub-queries that help generate specific answers for a given data context. + +=== Example call + +[source,typescript] +---- +const result = await callMCPTool("getRelevantQuestions", { + query: "show me sales data", // User's natural language query + datasourceIds: ["model-guid-123"], // Array of worksheet/datasource GUIDs + additionalContext: "User is interested in the data for underperforming regions and products" +}); +---- + +=== Response + +[source,json] +---- +{ + "questions": [ + "What is the total sales revenue by region?", + "Which products have the highest revenue?", + "What are the top selling categories?" + ] +} +---- + +Each returned question can then be passed individually into `getAnswer`. + +== getAnswer +Executes a natural language query for a given data context and returns the resulting data and visualization metadata. Clients can use this data and frame URL to render visualizations. + +=== Example call + +[source,typescript] +---- +const result = await callMCPTool("getAnswer", { + question: "Total sales by region", // Natural language question + datasourceId: "model-guid-123" // Worksheet/datasource GUID +}); +---- + +=== Response + +[source,json] +---- +{ + "question": "Total sales by region", + "session_identifier": "abc-123-def-456", + "generation_number": 2, + "data": "\"Region\",\"Total Sales\"\n\"East\",100000\n...", + "frame_url": "https://...", + "fields_info": "..." +} +---- + +Key fields are: + +* `session_identifier`: Unique session ID used to group answers. Required when creating a Liveboard from this answer using the `createLiveboard` MCP tool. +* `generation_number`: Version number for this answer. Required for Liveboard creation. +* `question`: The executed question; useful for display and to pass it into the `createLiveboard` request. +* `data`: Data returned in encoded format. Contains column headers and all returned rows in comma-separated format, which can be parsed to render tables or charts in your application. +* `frame_url`: Optional iframe URL for embedding the visualization in your UI. +* `fields_info`: Descriptive metadata about the fields and chart, useful for explanations. + +== createLiveboard + +Creates a ThoughtSpot Liveboard with one or more answers from the results. This is a two-step process and includes the following calls: + +. Call `getAnswer` to generate visualizations and obtain `session_identifier` and `generation_number`. +. Call `createLiveboard` with those values to create the Liveboard. + +=== Example call + +[source,typescript] +---- +const answerData = JSON.parse(answerResult.result.content); + +const liveboardResult = await callMCPTool("createLiveboard", { + name: "My Sales Dashboard", + noteTile: "My Sales Dashboard was created by TS MCP Chat", // Description text for the Liveboard + answers: [{ + question: answerData.question, // Display name for the Liveboard + session_identifier: answerData.session_identifier, + generation_number: answerData.generation_number + }] +}); +---- + +Required attributes are: + +* `noteTile`: Use this field for any Liveboard description or notes; a separate description field is not supported. +* `answers`: Required array. Each item must include `question`, `session_identifier`, and `generation_number` from a prior `getAnswer` call. + +=== Response + +[source,json] +---- +{ + "liveboardId": "liveboard-guid-here", + "name": "My Sales Dashboard", + "frame_url": "https://..." +} +---- + +Key fields are: + +* `liveboardId`: GUID of the created Liveboard. +* `name`: Name of the Liveboard. +* `frame_url`: URL that can be embedded to display the Liveboard. + + + + diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc new file mode 100644 index 000000000..976af140e --- /dev/null +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -0,0 +1,356 @@ += MCP tool reference (Spotter 3) +:toc: true +:toclevels: 3 + +:page-title: ThoughtSpot MCP tool reference guide +:page-pageid: mcp-tool-reference-spotter3 +:page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. + +The new ThoughtSpot MCP integration exposes a session-based workflow for running natural language analytics queries against your ThoughtSpot data sources. The pattern is always: **create a session** → **send a message** → **poll for updates**. + +== create_analysis_session +Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. + +Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling `create_analysis_session` again. + +=== Input parameter +The `data_source_id` is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. + +=== Example call + +[source,javascript] +---- +const session = await callMCPTool("create_analysis_session", { + data_source_id: "model-guid-123" // Optional — GUID of the ThoughtSpot worksheet or model to query. Omit to let ThoughtSpot automatically select the most relevant data source. +}); +---- + +[source,python] +---- +call_mcp_tool( + "create_analysis_session", + { + "data_source_id": "model-guid-123" # Optional — GUID of the ThoughtSpot worksheet or model to query. + }, +) +---- + +=== Response + +[source,json] +---- +{ +"analytical_session_id": "session-guid-abc123" +} +---- + +* `analytical_session_id`: Session ID. Pass this to `send_session_message` and `get_session_updates`. + +* Always capture the returned `analytical_session_id`. It is required for all subsequent calls. + +== send_session_message +Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use `get_session_updates` to retrieve the response. + +=== Input parameters + +[cols="2,4", options="header"] +|==== +|Field|Description + +|`analytical_session_id` | The session to send the message to. Obtained from the `create_analysis_session` call. +|`message`|A natural language analytical question or follow-up to send to the ThoughtSpot agent. +|`additional_context` + +__Optional__|Can be used to provide external information relating to the question. For example, “The user’s fiscal year starts in April”, or “The user is a manager of the West region”. +|==== + +=== Example call + +[source,javascript] +---- +const sendMessage = await callMCPTool("send_session_message", { + analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. + message: "What were total sales by region last quarter?", // User's natural language question. + additional_context: "The user's fiscal year starts in April. " + + "Focus on underperforming regions only." // Optional — external information to influence the analysis. +}); +---- + +[source,python] +---- +call_mcp_tool( + "send_session_message", + { + "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. + "message": "What were total sales by region last quarter?", # User's natural language question. + "additional_context": ( # Optional — external information + "The user's fiscal year starts in April." + "Focus on underperforming regions only." # to influence the analysis. + ), + }, +) +---- + +=== Response + +[source,json] +---- +{ + "success": true +} +---- + +* `success`: Confirms whether the message was successfully received by the agent. + +[NOTE] +==== +* After a successful send, immediately begin polling with `get_session_updates`. +* Do not send a second message until `get_session_updates` returns `is_done: true`. The agent processes one message at a time per session. +* To ask a follow-up question, reuse the same `analytical_session_id`. There is no need to create a new session. +==== + +== get_session_updates + +Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after `send_session_message` until `is_done` is `true`. + +**Important**: A single call to `get_session_updates` will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture. + +=== Input parameters +Send the `analytical_session_id` to specify the session to retrieve updates for. + +=== Example call + +[source,typescript] +---- +const updates = await callMCPTool("get_session_updates", { + analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call. +}); +---- + +[source,python] +---- +call_mcp_tool( + "get_session_updates", + {"analytical_session_id": "sess_abc123"}, # Session ID from create_analysis_session. +) +---- + +=== Response + +Poll returning intermediate updates with the "is_thinking" response: + +[source,json] +---- +{ + "is_done": false, + "session_updates": [ + { + "is_thinking":true, + "type":"text_chunk", + "text":"Let me look at your sales data by region...", + }, + ] +} +---- + +Poll returning final updates: + +[source,json] +---- +{ + "is_done": true, + "session_updates":[ + { + "is_thinking":false, + "type":"text-chunk", + "text":"Data broken down by region..." + }, + { + "is_thinking":false, + "type":"text", + "text":"I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April." + }, + { + "is_thinking":false, + "type":"answer", + "answer_title":"Total Sales by Region — Q4 2025", + "answer_query":"total sales by region last quarter", + "iframe_url":"https://your-instance.thoughtspot.cloud/embed/...", + "answer_id":"answer-guid-xyz789" + } + ] +} +---- + +=== Handling streamed responses +Spotter queries are processed asynchronously and streamed in real time. This means the full response is never contained in a single `get_session_updates` call. + +Each call to `get_session_updates` returns only the updates generated since the previous call. The `session_updates` array may indicate that Spotter is still processing with an `is_thinking` state, may include intermediate updates, or may contain several updates at once. Updates typically arrive as text or text-chunk types, reflecting Spotter’s ongoing reasoning, before the final answer update is provided. This intermediate content shows Spotter’s step-by-step thought process and should be preserved and presented to the user for transparency into how the answer is derived. + +A typical response sequence might look like: + +. Thinking narration: `text-chunk` updates with `is_thinking` state describing what Spotter is doing. +. Clarifications or caveats: `text` updates explaining assumptions, filters applied, or potential ambiguities in the question. +. Intermediate conclusions: partial results or contextual notes before the final answer. +. The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. + +This means a complete response might span between 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content — the thinking, the narration, and the final answer — should be accumulated and presented together to give the user the full picture. + +=== Type definition: session_update + +Each item in the `session_updates` list is a `session_update` object. The `type` field determines which other fields are present. + +[cols="2,2,4", options="header"] +|==== +|Field|Type|Description +.3+|`type` +|`"text"`|A complete natural language message from the agent. +|`"text-chunk"` | A streaming chunk of a longer message. Concatenate all chunks to reconstruct the full text. +|`"answer"`|Populates `answer_title`, `answer_query`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL. +|`text`|__String__|The text content of the message. Present only when `type` is `"text"` or `"text-chunk"`. For `"text-chunk"` updates, concatenate all chunks in order to form the complete message. +|`answer_title`|__String__|A human-readable title describing what the answer shows. Present only when `type` is `"answer"`. +|`answer_query`|__String__|The search query ThoughtSpot used to generate the answer. Present only when `type` is `"answer"`. Useful for explaining to users what data was queried or for diagnosing unexpected results. +|`iframe_url`|__String__|An embeddable URL for rendering the answer as an interactive visualization. Present only when `type` is `"answer"`. Use this to display a live chart or table if your environment supports iframes. +|==== + + +== create_dashboard + +Create a ThoughtSpot dashboard from answers generated in an analysis session. + +* Call this only after `get_session_updates` returns `is_done: true`, because you need the `answer_id` values from completed answer updates. +* Collect all updates where type is answer across every poll of `get_session_updates`. Each one produces an `answer_id` you can include in the dashboard. +* The `note_tile` should summarize the full analysis. It is the first thing a viewer sees on the dashboard. +* Multiple answers from the same session or across multiple sessions can be combined into a single dashboard. + +=== Input parameters + +[cols="2,4", options="header"] +|==== +|Field|Description + +|`title` |Required. Title of the dashboard to be created. +|`answers`|Required. List of answer objects to add to the dashboard. Each answer requires an `answer_id` (from `get_session_updates` where `type` is `answer`) and a `title`. +|`note_tile`| Required. An HTML summary of the analysis and answers, rendered as a styled tile on the dashboard. Must be a single line with no line breaks. Use `
` for spacing within the HTML. Include emojis, colors, and a `"Generated on