From bc72d8e54ab284cf504e786a2516d481d30a0157 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 8 Oct 2025 23:27:57 +0530 Subject: [PATCH 1/9] mcp abbr fix --- modules/ROOT/pages/mcp-integration.adoc | 2 +- modules/ROOT/pages/spotter-apis.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index af40cd213..4f5ebcb00 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,7 +6,7 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Multi-Client Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. +ThoughtSpot’s Agentic Model Context Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. The MCP tools of the Agentic MCP Server support the following functions: diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 622bc2a10..6eb6daad5 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -68,7 +68,7 @@ The following AI API endpoints allow you to initiate a conversation session with __This is a legacy API endpoint and will be deprecated in an upcoming release version__. === Create a conversation session with Spotter agent -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint allows you to initiate a new conversation session with ThoughtSpot's AI Agent. Developers and system integrators embedding Spotter into agentic workflows, custom applications, or internal MCP (Managed Content Platform) servers, can use this API endpoint to create a conversation session from different data contexts such as Answers, Liveboards, or Models. +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint allows you to initiate a new conversation session with ThoughtSpot's AI Agent. Developers and system integrators embedding Spotter into agentic workflows, custom applications, or internal Model Context Protocol (MCP) servers, can use this API endpoint to create a conversation session from different data contexts such as Answers, Liveboards, or Models. [NOTE] ==== From 88517cba7c27b909258122659fc49b668f03d34f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Sat, 18 Oct 2025 00:44:44 +0530 Subject: [PATCH 2/9] mcp doc updates --- modules/ROOT/pages/mcp-integration.adoc | 235 +++++++++++++++++++++--- 1 file changed, 205 insertions(+), 30 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 4f5ebcb00..7fa1b28cb 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,52 +6,65 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Model Context Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. +ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. -The MCP tools of the Agentic MCP Server support the following functions: +The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot licenses: -* Ask natural language questions and get data in a structured format from ThoughtSpot -* Retrieve relevant analytical questions based on user queries -* Create a Liveboard with the answers generated from the queries -* Get data source recommendations based on a user's query and intent +* Enterprise Edition of ThoughtSpot Analytics +* ThoughtSpot Embedded subscription + +To learn about our available subscription options and to et started, please contact your ThoughtSpot Sales representative == Integration overview The Agentic MCP Server integration requires the following core components and authentication framework: MCP Server:: -The MCP Server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP Server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP Server can be hosted by ThoughtSpot or by customers in their own environment. +The MCP Server exposes a set of tools that can be invoked by an LLM or external AI. ThoughtSpot's MCP Server acts as a bridge between the LLM/agent and ThoughtSpot application backend. -MCP tools, resources, and AI APIs:: -MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP Server supports the following tools: +MCP tools and resources:: +MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. +* Ask natural language questions and get data in a structured format from ThoughtSpot +* Retrieve relevant analytical questions based on user queries +* Create a Liveboard with the answers generated from the queries +* Get data source recommendations based on a user's query and intent ++ +Currently, the MCP Server supports the following tools: ++ * `ping` to test connection to ThoughtSpot * `getRelevantQuestions` to get relevant analytical questions + -The `getRelevantQuestions` tool calls xref:spotter-apis.adoc#_get_relevant_questions[/api/rest/2.0/ai/relevant-questions/] API and gets relevant data questions for a given data context by breaking down a user's query. +The `getRelevantQuestions` tool to fetch relevant data questions for a given data context by breaking down a user's query. * `getAnswer` to execute the queries and fetch data + -The `getAnswer` tool calls xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[/api/rest/2.0/ai/agent/converse/sse] API and generates answers and insights for a given data context. +The `getAnswer` tool generates answers and insights for a given data context. * `createLiveboard` to create a Liveboard in ThoughtSpot + The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from user's query. * `getDataSourceSuggestions` to get data source suggestions + Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. -MCP host/client:: -The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP Server, and enables agentic workflows. +MCP client/ LLM agent:: +The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with ThoughtSpot MCP Server +This is the model or system that processes the user’s natural language input, determines which tool to call, and integrates the tool results into its final output. +//// Configuration settings to enable the integration:: Integration requires configuration, typically via a config file, to specify server addresses, credentials, and other connection details. +//// Authentication and security settings:: + * Access to ThoughtSpot instance: + -For MCP Server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + -To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users +For MCP Server connection, users require access to a ThoughtSpot instance. For tool invocation, the MCP server must accept authenticated requests and the LLM tool specification must carry those credentials or headers. + +ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + +* SAML redirect settings: + +For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. + +* To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users require data download privilege. * CSP and CORS settings: + To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP Server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. -* SAML redirect settings: + -For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. * Client connection configuration: + MCP Server integration also requires configuration on the client side, typically via a config file, to include the MCP Server addresses, credentials, and other details. + === How it works When the MCP Server integration is enabled, your host app connects to ThoughtSpot and enables the following workflow: @@ -86,6 +99,13 @@ Before you begin, verify if your application setup has the following: * Your application users have at least view access to the data source objects to query data and get answers. * Row-level and column-level security rules are configured for data security and access control. +To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: + +. On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. +. Add the MCP Server domain to CSP and CORS allowlists. +. If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. + +//// === Configure security settings on ThoughtSpot To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: @@ -93,12 +113,170 @@ To allow the secure communication between the MCP Server and your ThoughtSpot in . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. . Add the MCP Server domain to CSP and CORS allowlists. . If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. +//// + +=== Connect your client to MCP server + +If using a client that supports remote MCPs natively such as Claude AI, use the following MCP server URL: +---- +https://agent.thoughtspot.app/mcp +---- + +For OpenAI ChatGPT Deep Research, use the following URL: +---- +https://agent.thoughtspot.app/openai/mcp +---- + +=== Call MCP tools via LLM APIs + +ThoughtSpot remote MCP server exposes a set of tools that can be invoked by an LLM. To call an MCP tool, you can use the LLM APIs and methods: + +* OpenAI: via responses API +* Claude AI: via messages API +* Gemini AI: via Gemini Python/Typescript SDK -=== Add MCP Server to the MCP client's config +==== ClaudeAI -If your MCP client supports remote MCP Servers, add the MCP Server URL to the client's config file. +Claude’s MCP connector feature enables you to connect to remote MCP servers directly from the Messages API. -MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP Servers. In such a case, add the URL with arguments shown in this example: +To connect to a remote MCP server, specify the model and include the following properties in the `mcp_servers` and messages arrays: + +* In the ``mcp_servers` array, include these parameters: + +** `type` + +__String__. Type. Currently only `url` is supported. +** `url` + +__String__. The URL of the remote MCP Server endpoint. Must start with `https://`. +** `name` +__String__. A unique identifier/label for the MCP Server. It will be used in MCP tool call blocks to identify the server and to disambiguate tools to the LLM. +** `authorization_token` + +__String__. OAuth authorization token (TS_AUTH_TOKEN) along with the ThoughtSpot application instance URL. In the above example, authorization token is prefixed and the ThoughtSpot host URL is added with the `@` symbol. + +* `model` + +Claude’s model to use. For example, claude-sonnet-4-20250514, which will determine whether to invoke the MCP tools from ThoughtSpot remote MCP server context specified in the request. +* `messages` +In the messages array, specify a natural language question and the user role. + +[source,cURL] +---- +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "X-API-Key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: mcp-client-2025-04-04" \ + -d '{ + "model": "claude-sonnet-4-20250514", + "max_tokens": 1000, + "messages": [{ + "role": "user", + "content": "How do I increase my sales ?" + }], + "mcp_servers": [ + { + "type": "url", + "url": "https://agent.thoughtspot.app/bearer/mcp", + "name": "thoughtspot", + "authorization_token": "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud" + } + ] + }' +---- + +When invoked, Claude’s internal tool-calling mechanism calls the MCP endpoint with the provided token, retrieves analytics data, and then continues generating its answer including that result. + +==== OpenAI +To enable tool calling and retrieve live analytics data from ThoughtSpot via OpenAI, you can use the Responses API endpoint. For Remote MCP server tool calling, you'll need the MCP server URL and an OAuth access token. + +The following cURL request calls the OpenAI Responses API endpoint `https://api.openai.com/v1/responses` with a JSON payload that contains the following properties and information in the `tools` array: + +* `server_url` + +The URL of the ThoughtSpot MCP Server. +* `server_label` + +Label of the ThoughtSpot MCP Server +* `type` + +Type of tool. For example, MCP. +* `headers` + +Additional headers needed for authentication, for example, authentication token and the URL of the ThoughtSpot host. + +Additionally, you can also include the natural language query string as `input` in the request. + +[source,cURL] +---- +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "tools": [ + { + "type": "mcp", + "server_label": "thoughtspot", + "server_url": "https://agent.thoughtspot.app/bearer/mcp", + "headers": { + "Authorization": "Bearer $TS_AUTH_TOKEN", + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + } + } + ], + "input": "How can I increase my sales ?" +}' +---- + +==== Gemini +For Gemini, you can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively and can pass tool definitions and call tools. + +When using the Gemini SDK, you can pass a session linked to the remote MCP server, so that the SDK can handle tool calling. + +[source,TypeScript] +---- +import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai'; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + +// Create server parameters for stdio connection +const serverParams = new StreamableHTTPClientTransport(new URL("https://agent.thoughtspot.app/bearer/mcp"), { + requestInit: { + headers: { + "Authorization": "Bearer $TS_AUTH_TOKEN", // Read below how to get the $TS_AUTH_TOKEN + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + }, + } +}); + +const client = new Client( + { + name: "example-client", + version: "1.0.0" + } +); + +// Configure the client +const ai = new GoogleGenAI({}); + +// Initialize the connection between client and server +await client.connect(serverParams); + +// Send request to the model with MCP tools +const response = await ai.models.generateContent({ + model: "gemini-2.5-flash", + contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`, + config: { + tools: [mcpToTool(client)], // uses the session, will automatically call the tool + // Uncomment if you **don't** want the sdk to automatically call the tool + // automaticFunctionCalling: { + // disable: true, + // }, + }, +}); +console.log(response.text) + +// Close the connection +await client.close(); +---- + +=== MCP clients (Claude Desktop) + +For clients such as Claude Desktop, Windsurf, Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: [source,JSON] ---- @@ -113,7 +291,6 @@ MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote M } } } - ---- After updating the config file: @@ -122,6 +299,7 @@ After updating the config file: . Restart your MCP client to load the new configuration. + If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + ++ For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: + [.bordered] @@ -135,21 +313,19 @@ For example, on Claude Desktop, click the Search and tools icon to view the MCP [.bordered] [.widthAuto] image::./images/mcp-tools-claude.png[Claude Desktop] - ++ You can adjust tool access, resources, instructions to data models, object permissions, and user privileges as needed. To get insights, the user requires view access to the data source objects and data download privilege. -=== Verify the query and response workflow - -* Select a data source to set the context of your query. + -For example, on Claude Desktop, click the `+` icon and select a data source. +. Select a data source to set the context of your query. + +Click the `+` icon in Claude Desktop and select a data source. + [.bordered] [.widthAuto] image::./images/datasource-selection.png[Claude Desktop] -* Ask an analytics question to trigger the query and response workflow. -* Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. +. Ask an analytics question to trigger the query and response workflow. +. Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. + [.bordered] [.widthAuto] @@ -160,14 +336,13 @@ image::./images/query-response-claude.png[Claude query response] [.widthAuto] image::./images/query-response-claude2.png[Claude query response 2] -* Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. +. Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. + [.bordered] [.widthAuto] image::./images/create-lb-claude.png[Liveboard creation] - == Configuration considerations and best practices * Users must have at least view access to the data source. Otherwise, it may lead to empty results. From 26bf45f983d39db0000460554997540d576f75cb Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Sat, 18 Oct 2025 12:29:40 +0530 Subject: [PATCH 3/9] tool calling and updates for legal --- modules/ROOT/pages/mcp-integration.adoc | 190 +++++++++++++++--------- 1 file changed, 116 insertions(+), 74 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 7fa1b28cb..6dca73af7 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -8,12 +8,13 @@ ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. -The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot licenses: +The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + +To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot licenses: * Enterprise Edition of ThoughtSpot Analytics * ThoughtSpot Embedded subscription -To learn about our available subscription options and to et started, please contact your ThoughtSpot Sales representative +To learn about our available subscription options and to get started, please contact your ThoughtSpot Sales representative. == Integration overview @@ -29,9 +30,10 @@ MCP tools are the actions that the MCP Server exposes to the agent for interacti * Retrieve relevant analytical questions based on user queries * Create a Liveboard with the answers generated from the queries * Get data source recommendations based on a user's query and intent + + Currently, the MCP Server supports the following tools: -+ + * `ping` to test connection to ThoughtSpot * `getRelevantQuestions` to get relevant analytical questions + The `getRelevantQuestions` tool to fetch relevant data questions for a given data context by breaking down a user's query. @@ -42,6 +44,7 @@ The `createLiveboard` tool calls the Liveboard creation workflow and creates a L * `getDataSourceSuggestions` to get data source suggestions + Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. + MCP client/ LLM agent:: The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with ThoughtSpot MCP Server This is the model or system that processes the user’s natural language input, determines which tool to call, and integrates the tool results into its final output. @@ -67,20 +70,16 @@ MCP Server integration also requires configuration on the client side, typically === How it works -When the MCP Server integration is enabled, your host app connects to ThoughtSpot and enables the following workflow: - -. User initiates a request. + -The user sends a query to get data from a specific ThoughtSpot data model or context. -. AI agent receives the request and discovers the MCP tools + -The agent discovers MCP tools available in its environment and processes the request to the MCP Server, specifying the data model or context and the user's query. -. MCP Server receives the request and executes actions via tools + -The MCP Server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. -. The MCP Server sends the response to the MCP host. -. The agent receives the response and constructs the output + -The agent receives the response from the MCP host, constructs the output, and presents it to the user. -. User receives the response + -The user can refine the analysis or choose a direction for further exploration. + -For example, after receiving relevant questions and answer, the user can send follow-up questions or send a Liveboard creation request. +The MCP Server integration with an agentic framework or LLM clients enables the following workflow: + +. User sends a query to get data from a specific ThoughtSpot data model context. +. The LLM / AI agent receives the request and sends it to the MCP server endpoint with the user's query. +. The MCP server responds with the available tools. +. The LLM / AI Agent determines the appropriate MCP tool to call. Based on the user's query or prompt, the MCP tools are invoked. For example, to get information for a specific data context from ThoughtSpot, break down the user's query into relevant questions or create an artifact in ThoughtSpot programmatically. +. The MCP server processes the request and returns the result. +. The agent receives the response, constructs the output, and presents it to the user. +. User receives the response. The user can refine the analysis with follow-up queries for further exploration or ask a new question. + +For example, after receiving relevant questions and answers, the user can send follow-up questions or initiate a Liveboard creation request. The following figure illustrates the sequence of workflows in a typical MCP Server integration setup: @@ -99,7 +98,7 @@ Before you begin, verify if your application setup has the following: * Your application users have at least view access to the data source objects to query data and get answers. * Row-level and column-level security rules are configured for data security and access control. -To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: +To enable secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. . Add the MCP Server domain to CSP and CORS allowlists. @@ -115,7 +114,7 @@ To allow the secure communication between the MCP Server and your ThoughtSpot in . If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. //// -=== Connect your client to MCP server +=== Connect your client to the MCP Server If using a client that supports remote MCPs natively such as Claude AI, use the following MCP server URL: ---- @@ -127,35 +126,48 @@ For OpenAI ChatGPT Deep Research, use the following URL: https://agent.thoughtspot.app/openai/mcp ---- +For MCP clients such as Claude Desktop, Windsurf, Cursor, that do not support remote MCP Server, you must xref:mcp-integration.adoc#_connecting_other_mcp_clients_claude_desktop[add the MCP server configuration to your MCP client settings]. + === Call MCP tools via LLM APIs -ThoughtSpot remote MCP server exposes a set of tools that can be invoked by an LLM. To call an MCP tool, you can use the LLM APIs and methods: +ThoughtSpot remote MCP Server acts as a wrapper over the ThoughtSpot APIs, making them available as tools for agent frameworks or LLMs such as Claude or OpenAI. It exposes specific tools to get relevant questions, answer, datasource suggestions, or create a Liveboard, which can be invoked by the LLMs in response to a user's query or prompt. + +To enable tool calling: -* OpenAI: via responses API -* Claude AI: via messages API -* Gemini AI: via Gemini Python/Typescript SDK +* Register the ThoughtSpot MCP Server endpoint as a tool provider in your LLM or agent framework. +* Provide an authentication (OAuth or token-based) token. + +You can generate an authentication token for a specific user from ThoughtSpot via a `POST` call to the `/api/rest/2.0/auth/token/full` REST API endpoint. + +Logged-in users can view the authentication token for their current session by using the `/api/rest/2.0/auth/session/token` REST API endpoint or by opening the following URL in a new tab on the web browser: ++ +`https://{your-ts-instance}/api/rest/2.0/auth/session/token` -==== ClaudeAI +To connect to the MCP Server and call tools, use the LLM APIs and methods: -Claude’s MCP connector feature enables you to connect to remote MCP servers directly from the Messages API. +* xref:mcp-integration.adoc#_claude[Claude (via messages API)] +* xref:mcp-integration.adoc#_openai[OpenAI (via Responses API] +* xref:mcp-integration.adoc#_gemini[Gemini (via Gemini Python/Typescript SDK)] -To connect to a remote MCP server, specify the model and include the following properties in the `mcp_servers` and messages arrays: +==== Claude MCP connector +Claude’s MCP connector feature enables you to connect to remote MCP Servers directly from the Messages API. -* In the ``mcp_servers` array, include these parameters: +To connect to the ThoughtSpot remote MCP Server, specify the following properties in the API request: +* `mcp_servers` + +In the `mcp_servers` array, include these parameters: + ** `type` + -__String__. Type. Currently only `url` is supported. +__String__. Type. Specify the type as `url`. ** `url` + __String__. The URL of the remote MCP Server endpoint. Must start with `https://`. -** `name` -__String__. A unique identifier/label for the MCP Server. It will be used in MCP tool call blocks to identify the server and to disambiguate tools to the LLM. +** `name` + +__String__. A unique identifier/label for the MCP Server. It will be used in the MCP tool call blocks to identify the server and to disambiguate tools to the LLM. ** `authorization_token` + -__String__. OAuth authorization token (TS_AUTH_TOKEN) along with the ThoughtSpot application instance URL. In the above example, authorization token is prefixed and the ThoughtSpot host URL is added with the `@` symbol. +__String__. OAuth authorization token (`TS_AUTH_TOKEN`) along with the ThoughtSpot application instance URL. In the following example, authorization token is prefixed, and the ThoughtSpot host URL is added with the `@` symbol. + +* `messages` + +In the `messages` array, specify a natural language question in `content` and the user role in `role`. * `model` + -Claude’s model to use. For example, claude-sonnet-4-20250514, which will determine whether to invoke the MCP tools from ThoughtSpot remote MCP server context specified in the request. -* `messages` -In the messages array, specify a natural language question and the user role. +LLM model to use for processing queries and interacting with tools. For example, claude-sonnet-4-20250514. [source,cURL] ---- @@ -182,23 +194,60 @@ curl https://api.anthropic.com/v1/messages \ }' ---- -When invoked, Claude’s internal tool-calling mechanism calls the MCP endpoint with the provided token, retrieves analytics data, and then continues generating its answer including that result. +//// +[source,TypeScript] +---- +import { Anthropic } from '@anthropic-ai/sdk'; + +const anthropic = new Anthropic(); + +const response = await anthropic.beta.messages.create({ + model: "claude-sonnet-4-5", + max_tokens: 1000, + messages: [ + { + role: "user", + content: "How do I increase my sales ?", + }, + ], + mcp_servers: [ + { + type: "url", + url: "https://agent.thoughtspot.app/bearer/mcp", + name: "thoughtspot", + authorization_token: "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud", + }, + ], + betas: ["mcp-client-2025-04-04"], +}); +---- +//// + +The request uses Claude’s internal tool-calling mechanism to call the MCP endpoint with the provided token, discover the available tools, and retrieve data for the user's query. + +For more information, see the link:https://docs.claude.com/en/docs/agents-and-tools/mcp-connector[Claude MCP connector documentation, window=_blank]. + +==== OpenAI API for MCP tool calling +To enable tool calling and retrieve data from ThoughtSpot via OpenAI, you can use the Responses API endpoint. -==== OpenAI -To enable tool calling and retrieve live analytics data from ThoughtSpot via OpenAI, you can use the Responses API endpoint. For Remote MCP server tool calling, you'll need the MCP server URL and an OAuth access token. +To connect to the ThoughtSpot remote MCP server, call the `https://api.openai.com/v1/responses` API endpoint and specify the following properties in the API request: -The following cURL request calls the OpenAI Responses API endpoint `https://api.openai.com/v1/responses` with a JSON payload that contains the following properties and information in the `tools` array: +* `tools` + +In the `tools` array, include these parameters: -* `server_url` + -The URL of the ThoughtSpot MCP Server. -* `server_label` + +** `server_url` + +The URL of the ThoughtSpot MCP Server. Use the full path of the MCP server URL. +** `server_label` + Label of the ThoughtSpot MCP Server -* `type` + +** `type` + Type of tool. For example, MCP. -* `headers` + -Additional headers needed for authentication, for example, authentication token and the URL of the ThoughtSpot host. +** `headers` + +Additional headers needed for authentication, for example, the authentication token and URL of the ThoughtSpot host. -Additionally, you can also include the natural language query string as `input` in the request. +* `input` + +Include the natural language query string as `input`. +* `model` + +LLM model to use for processing queries and interaction with tools. For example, GPT-5 or GPT 4.1. [source,cURL] ---- @@ -222,10 +271,15 @@ curl https://api.openai.com/v1/responses \ }' ---- -==== Gemini -For Gemini, you can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively and can pass tool definitions and call tools. +If the API request is successful, the LLM discovers the available MCP tools from the MCP Server endpoint. Once the model has access to these tools, it determines the tool to call depending on the user's query and what's in the model's context. + +For more information, see link:https://platform.openai.com/docs/guides/tools-connectors-mcp[Open AI Connectors and MCP Server Documentation]. -When using the Gemini SDK, you can pass a session linked to the remote MCP server, so that the SDK can handle tool calling. +==== Gemini SDK + +You can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively, and can pass tool definitions and call tools. + +In the following example, a session linked to the ThoughtSpot remote MCP Server is passed along with the authorization token and the ThoughtSpot host, so that the SDK can handle tool calling. [source,TypeScript] ---- @@ -237,7 +291,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/ const serverParams = new StreamableHTTPClientTransport(new URL("https://agent.thoughtspot.app/bearer/mcp"), { requestInit: { headers: { - "Authorization": "Bearer $TS_AUTH_TOKEN", // Read below how to get the $TS_AUTH_TOKEN + "Authorization": "Bearer $TS_AUTH_TOKEN", "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" }, } @@ -274,7 +328,13 @@ console.log(response.text) await client.close(); ---- -=== MCP clients (Claude Desktop) +For additional information, refer to the following resources: + +* For more information about Gemini API MCP tool calling, see link:https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#mcp[Function calling with the Gemini API documentation, window=_blank]. +* A link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-google-adk-trusted-auth[developer example with Google ADK and Python implementation] is also available in the link:https://github.com/thoughtspot/developer-examples[ThoughtSpot Developer Examples GitHub repository, window=_blank]. +* The ThoughtSpot MCP server can also be installed as a Gemini CLI extension. For more information, see link:https://github.com/google-gemini/gemini-cli[Gemini CLI, window=_blank]. + +=== For clients that do not support the remote MCP server For clients such as Claude Desktop, Windsurf, Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: @@ -298,7 +358,7 @@ After updating the config file: . When prompted to connect your ThoughtSpot instance, add the URL of your application instance and complete authentication. . Restart your MCP client to load the new configuration. + -If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + +If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: + @@ -308,36 +368,18 @@ image::./images/claudeDesktop.png[Claude Desktop] . Verify if the MCP tools are available. + For example, on Claude Desktop, click the Search and tools icon to view the MCP tools. - + [.bordered] [.widthAuto] image::./images/mcp-tools-claude.png[Claude Desktop] -+ -You can adjust tool access, resources, instructions to data models, object permissions, and user privileges as needed. To get insights, the user requires view access to the data source objects and data download privilege. - -. Select a data source to set the context of your query. + -Click the `+` icon in Claude Desktop and select a data source. - -+ -[.bordered] -[.widthAuto] -image::./images/datasource-selection.png[Claude Desktop] -. Ask an analytics question to trigger the query and response workflow. -. Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. +. Select a data source to set the context of your query and verify the request and response flow. + [.bordered] [.widthAuto] image::./images/query-response-claude.png[Claude query response] -+ -[.bordered] -[.widthAuto] -image::./images/query-response-claude2.png[Claude query response 2] - . Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. - + [.bordered] [.widthAuto] @@ -354,9 +396,9 @@ image::./images/create-lb-claude.png[Liveboard creation] * Check the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repo, window=_blank] for implementation instructions. * Check your MCP client's documentation for instructions on how to connect to MCP Servers. -* To understand ThoughtSpot agentic analytics capabilities and AI APIs, refer to the following documentation: +* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. +* To understand ThoughtSpot's agentic analytics capabilities and AI APIs, refer to the following documentation: -** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] -** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] +** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation, window=_blank] +** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation, window=_blank] ** xref:spotter-apis.adoc[Spotter AI APIs] -* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. \ No newline at end of file From 4b8067d8daf12c73029fb1123d4b95900051bf5e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Sat, 18 Oct 2025 13:12:38 +0530 Subject: [PATCH 4/9] SCAL-277967 and SCAL-277191 fixes --- modules/ROOT/pages/spotter-apis.adoc | 91 +++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 6eb6daad5..10733fffc 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -57,6 +57,14 @@ __Limited availability on ThoughtSpot Cloud instances from 10.13.0.cl onwards. P ==== //// +=== Locale setting in API requests + +When using the xref:spotter-apis.adoc#_generate_a_single_answer[Single Answer] and xref:spotter-apis.adoc#_send_a_question_to_generate_answer[Send message] APIs, the locale used for API requests depends on your application's locale settings: + +* If your application is set to "Use browser language," the API will not apply the default locale. In this case, you must explicitly include the desired locale code in the `Accept-Language` header of your API request. If you do not specify the locale, the API may not return responses in the expected language or format. +* If you have set a specific locale in your ThoughtSpot instance or user profile, the API will use this locale to generate responses, overriding the browser or OS locale + +To ensure consistent localization, set the `Accept-Language` header in your API requests when relying on browser language detection, or configure the locale explicitly in the user profile settings in ThoughtSpot. == Create a conversation session A conversation session acts as a container for maintaining continuity across user inputs, system responses, and agent-driven clarifications. Once created, users can send queries or ask follow-up questions to the conversation session to explore data and get further insights. @@ -82,17 +90,21 @@ To set the context for the conversation session, you must specify the metadata t [options='header'] |===== |Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. Specify the following values: +|`metadata_context` a| Defines the data context for the conversation. The context type is mandatory. + +Specify the following values: * `type` + Metadata type. Valid values are: -** `answer` - To use an existing Spotter-generated Answer as the object -** `liveboard` - To use an existing Liveboard as data object -** `data_source` - To create a new conversation session using data objects such as Model. -+ +** `data_source` - To set a data source context for the conversation session. + +If the context type is `data_source`, you must define the `data_source_context` in the request payload. +** `answer` - To use an existing Spotter-generated Answer as the object. + +If the context type is `answer`, the user must provide both `data_source_context` and `answer_context` in the request payload. +** `liveboard` - To use an existing Liveboard as context. + +If the context type is `liveboard`, the user must provide `data_source_context`, `liveboard_context`, and `answer_context` in the request payload. * `answer_context` + -If the metadata type is set as `answer`, specify the following attributes: +If the metadata type is set as `answer` or `liveboard`, specify the following attributes: ** `session_identifier`: __string__, Unique ID representing the answer session. ** `generation_number`: __Integer__. Specific generation/version number of the answer within a conversation session. + @@ -101,7 +113,7 @@ The session identifier and generation numbers are assigned to the Answers genera * `liveboard_context` + If the metadata type is set as `liveboard`, specify the GUID of the Liveboard and visualization. * `data_source_context` + -If the metadata type is set as `data_source`, specify the GUID of the data source object. +Specify the GUID of the data source object. |`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: @@ -115,6 +127,8 @@ __Boolean__. Allows Spotter to use reasoning for deep analysis and precise respo ==== Example request +The following example shows the request payload for the `data_source` context type: + [source,cURL] ---- curl -X POST \ @@ -137,6 +151,63 @@ curl -X POST \ }' ---- +The following example shows the request payload for the `liveboard` context type: +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "liveboard", + "answer_context": { + "session_identifier": "c3a00fa7-fd01-4d58-8c84-0704df986d9d", + "generation_number": 2 + }, + "liveboard_context": { + "liveboard_identifier": "cffdc614-0214-42ba-9f57-cb6e8312fe5a", + "visualization_identifier": "da0ed3da-ce1f-4071-8876-74d551b05faf" + }, + "data_source_context": { + "guid": "54beb173-d755-42e0-8f73-4d4ec768114f" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + +The following example shows the request payload for the `answer` context type: + +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "answer", + "answer_context": { + "session_identifier": "f131ca07-47e9-4f56-9e21-454120912ae1", + "generation_number": 1 + }, + "data_source_context": { + "guid": "cd252e5c-b552-49a8-821d-3eadaa049cca" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + ==== API response If the API request is successful, the API returns the conversation ID. You can use this ID to send follow-up questions to the conversation session. @@ -146,7 +217,7 @@ If the API request is successful, the API returns the conversation ID. You can u {"conversation_id":"q9tZYf_6WnFC"} ---- -Note the conversation ID for further agentic interactions and API calls. +Note the conversation ID for subsequent agentic interactions and API calls. === Create a conversation session (legacy API endpoint) To create a conversation session, send a `POST` request body with the data source ID and search token string to the `/api/rest/2.0/ai/conversation/create` API endpoint. @@ -728,6 +799,7 @@ To send a question to an ongoing conversation session or ask follow-up questions curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/conversation/03f48527-b973-4efa-81fd-a8568a4f9e78/converse' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ @@ -815,7 +887,6 @@ The API retrains the context of the initial question and returns a response: |=== //// - == Generate a single Answer To generate an Answer from a natural language search query, send a `POST` request to the `/api/rest/2.0/ai/answer/create` API endpoint. In the request body, include the query and the data source ID. @@ -836,6 +907,7 @@ To generate an Answer from a natural language search query, send a `POST` reques curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/answer/create' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN} \ --data-raw '{ @@ -875,7 +947,6 @@ Note the session ID and generation number. To export the result generated from t }] ---- - [#process_results] == Process results generated from Spotter APIs To generate an Answer using the data returned from the Spotter APIs, use the following options: From bd1f757c0ba5fcca41ef748b636ccff4ebf4cc92 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Sat, 18 Oct 2025 17:53:59 +0530 Subject: [PATCH 5/9] typo fixes --- modules/ROOT/pages/mcp-integration.adoc | 10 +++++----- modules/ROOT/pages/spotter-apis.adoc | 16 +++++++--------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 6dca73af7..4c8c2fb9e 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -141,11 +141,11 @@ Logged-in users can view the authentication token for their current session by u + `https://{your-ts-instance}/api/rest/2.0/auth/session/token` -To connect to the MCP Server and call tools, use the LLM APIs and methods: +For information about calling MCP tools using LLM APIs and methods, see these sections: -* xref:mcp-integration.adoc#_claude[Claude (via messages API)] -* xref:mcp-integration.adoc#_openai[OpenAI (via Responses API] -* xref:mcp-integration.adoc#_gemini[Gemini (via Gemini Python/Typescript SDK)] +* xref:mcp-integration.adoc#_claude_mcp_connector[Claude MCP connector] +* xref:mcp-integration.adoc#_openai_api_for_mcp_tool_calling[OpenAI API] +* xref:mcp-integration.adoc#_gemini_api[Gemini API and function calling] ==== Claude MCP connector Claude’s MCP connector feature enables you to connect to remote MCP Servers directly from the Messages API. @@ -275,7 +275,7 @@ If the API request is successful, the LLM discovers the available MCP tools from For more information, see link:https://platform.openai.com/docs/guides/tools-connectors-mcp[Open AI Connectors and MCP Server Documentation]. -==== Gemini SDK +==== Gemini API You can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively, and can pass tool definitions and call tools. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 10733fffc..7cab136a1 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -57,7 +57,7 @@ __Limited availability on ThoughtSpot Cloud instances from 10.13.0.cl onwards. P ==== //// -=== Locale setting in API requests +=== Locale settings for API requests When using the xref:spotter-apis.adoc#_generate_a_single_answer[Single Answer] and xref:spotter-apis.adoc#_send_a_question_to_generate_answer[Send message] APIs, the locale used for API requests depends on your application's locale settings: @@ -90,18 +90,16 @@ To set the context for the conversation session, you must specify the metadata t [options='header'] |===== |Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. The context type is mandatory. - -Specify the following values: +|`metadata_context` a| Defines the data context for the conversation. * `type` + -Metadata type. Valid values are: +Metadata context type. The context type is mandatory. Select one of the following values: ** `data_source` - To set a data source context for the conversation session. + If the context type is `data_source`, you must define the `data_source_context` in the request payload. ** `answer` - To use an existing Spotter-generated Answer as the object. + -If the context type is `answer`, the user must provide both `data_source_context` and `answer_context` in the request payload. +If the context type is `answer`, you must define both `data_source_context` and `answer_context` in the request payload. ** `liveboard` - To use an existing Liveboard as context. + -If the context type is `liveboard`, the user must provide `data_source_context`, `liveboard_context`, and `answer_context` in the request payload. +If the context type is `liveboard`, you must define `data_source_context`, `liveboard_context`, and `answer_context` in the request payload. * `answer_context` + If the metadata type is set as `answer` or `liveboard`, specify the following attributes: @@ -111,9 +109,9 @@ If the metadata type is set as `answer` or `liveboard`, specify the following at The session identifier and generation numbers are assigned to the Answers generated from the Spotter AI REST APIs. These properties serve as the ID of the AI-generated Answer within the ThoughtSpot system. * `liveboard_context` + -If the metadata type is set as `liveboard`, specify the GUID of the Liveboard and visualization. +If the metadata type is set as `liveboard`, specify the GUIDs of the Liveboard and visualization. * `data_source_context` + -Specify the GUID of the data source object. +Specify the GUID of the data source object. Required parameter for all types of metadata context. |`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: From a1db8fb62bda415d44f70f5e35731fac466cdabf Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Sat, 18 Oct 2025 17:56:18 +0530 Subject: [PATCH 6/9] edits' --- modules/ROOT/pages/mcp-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 4c8c2fb9e..607d2d45a 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -14,7 +14,7 @@ To purchase the MCP Server subscription and enable the MCP Server in your enviro * Enterprise Edition of ThoughtSpot Analytics * ThoughtSpot Embedded subscription -To learn about our available subscription options and to get started, please contact your ThoughtSpot Sales representative. +To learn more about the MCP Server subscription options and to get started, please contact your ThoughtSpot Sales representative. == Integration overview From 0d43fc9cecda4e9102f71df5e5973fc61626e5ec Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 20 Oct 2025 14:53:22 +0530 Subject: [PATCH 7/9] edits --- modules/ROOT/pages/mcp-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 607d2d45a..0d17ad491 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -9,7 +9,7 @@ ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + -To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot licenses: +To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot license plans: * Enterprise Edition of ThoughtSpot Analytics * ThoughtSpot Embedded subscription From a56b53cea5d5922c960fff59bea947a332668ed9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Tue, 21 Oct 2025 21:44:02 +0530 Subject: [PATCH 8/9] Update mcp-integration.adoc --- modules/ROOT/pages/mcp-integration.adoc | 32 +++++++++++++------------ 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 0d17ad491..b3bdd28fd 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -40,13 +40,15 @@ The `getRelevantQuestions` tool to fetch relevant data questions for a given dat * `getAnswer` to execute the queries and fetch data + The `getAnswer` tool generates answers and insights for a given data context. * `createLiveboard` to create a Liveboard in ThoughtSpot + -The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from user's query. +The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from the user's query. + +//// * `getDataSourceSuggestions` to get data source suggestions + Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. - +//// MCP client/ LLM agent:: -The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with ThoughtSpot MCP Server +The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with the ThoughtSpot MCP Server. This is the model or system that processes the user’s natural language input, determines which tool to call, and integrates the tool results into its final output. //// @@ -57,11 +59,11 @@ Integration requires configuration, typically via a config file, to specify serv Authentication and security settings:: * Access to ThoughtSpot instance: + -For MCP Server connection, users require access to a ThoughtSpot instance. For tool invocation, the MCP server must accept authenticated requests and the LLM tool specification must carry those credentials or headers. + -ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + +For MCP Server connection, users require access to a ThoughtSpot instance. For tool invocation, the MCP server must accept authenticated requests, and the LLM tool specification must carry those credentials or headers. + +ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in users. + * SAML redirect settings: + For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. + -* To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users require data download privilege. +* To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create a Liveboard, users require the data download privilege. * CSP and CORS settings: + To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP Server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. * Client connection configuration: + @@ -75,7 +77,7 @@ The MCP Server integration with an agentic framework or LLM clients enables the . User sends a query to get data from a specific ThoughtSpot data model context. . The LLM / AI agent receives the request and sends it to the MCP server endpoint with the user's query. . The MCP server responds with the available tools. -. The LLM / AI Agent determines the appropriate MCP tool to call. Based on the user's query or prompt, the MCP tools are invoked. For example, to get information for a specific data context from ThoughtSpot, break down the user's query into relevant questions or create an artifact in ThoughtSpot programmatically. +. The LLM / AI Agent determines the appropriate MCP tool to call. Based on the user's query or prompt, the MCP tools are invoked. For example, to get information for a specific data context from ThoughtSpot, break down the user's query into relevant questions or programmatically create an artifact in ThoughtSpot. . The MCP server processes the request and returns the result. . The agent receives the response, constructs the output, and presents it to the user. . User receives the response. The user can refine the analysis with follow-up queries for further exploration or ask a new question. + @@ -107,7 +109,7 @@ To enable secure communication between the MCP Server and your ThoughtSpot insta //// === Configure security settings on ThoughtSpot -To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: +To allow secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. . Add the MCP Server domain to CSP and CORS allowlists. @@ -116,7 +118,7 @@ To allow the secure communication between the MCP Server and your ThoughtSpot in === Connect your client to the MCP Server -If using a client that supports remote MCPs natively such as Claude AI, use the following MCP server URL: +If using a client that supports remote MCPs natively, such as Claude AI, use the following MCP server URL: ---- https://agent.thoughtspot.app/mcp ---- @@ -126,11 +128,11 @@ For OpenAI ChatGPT Deep Research, use the following URL: https://agent.thoughtspot.app/openai/mcp ---- -For MCP clients such as Claude Desktop, Windsurf, Cursor, that do not support remote MCP Server, you must xref:mcp-integration.adoc#_connecting_other_mcp_clients_claude_desktop[add the MCP server configuration to your MCP client settings]. +For MCP clients such as Claude Desktop, Windsurf, and Cursor that do not support a remote MCP Server, you must xref:mcp-integration.adoc#_connecting_other_mcp_clients_claude_desktop[add the MCP server configuration to your MCP client settings]. === Call MCP tools via LLM APIs -ThoughtSpot remote MCP Server acts as a wrapper over the ThoughtSpot APIs, making them available as tools for agent frameworks or LLMs such as Claude or OpenAI. It exposes specific tools to get relevant questions, answer, datasource suggestions, or create a Liveboard, which can be invoked by the LLMs in response to a user's query or prompt. +ThoughtSpot remote MCP Server acts as a wrapper over the ThoughtSpot APIs, making them available as tools for agent frameworks or LLMs such as Claude or OpenAI. It exposes specific tools that can be invoked by the LLMs in response to a user's query or prompt. To enable tool calling: @@ -148,7 +150,7 @@ For information about calling MCP tools using LLM APIs and methods, see these se * xref:mcp-integration.adoc#_gemini_api[Gemini API and function calling] ==== Claude MCP connector -Claude’s MCP connector feature enables you to connect to remote MCP Servers directly from the Messages API. +The Claude’s MCP connector allows you to connect to remote MCP Servers directly from the Messages API. To connect to the ThoughtSpot remote MCP Server, specify the following properties in the API request: @@ -161,7 +163,7 @@ __String__. The URL of the remote MCP Server endpoint. Must start with `https:// ** `name` + __String__. A unique identifier/label for the MCP Server. It will be used in the MCP tool call blocks to identify the server and to disambiguate tools to the LLM. ** `authorization_token` + -__String__. OAuth authorization token (`TS_AUTH_TOKEN`) along with the ThoughtSpot application instance URL. In the following example, authorization token is prefixed, and the ThoughtSpot host URL is added with the `@` symbol. +__String__. OAuth authorization token (`TS_AUTH_TOKEN`) along with the ThoughtSpot application instance URL. In the following example, the authorization token is added as a prefix, and the ThoughtSpot host URL is added with the `@` symbol. * `messages` + In the `messages` array, specify a natural language question in `content` and the user role in `role`. @@ -324,7 +326,7 @@ const response = await ai.models.generateContent({ }); console.log(response.text) -// Close the connection +// Close the connection, await client.close(); ---- @@ -336,7 +338,7 @@ For additional information, refer to the following resources: === For clients that do not support the remote MCP server -For clients such as Claude Desktop, Windsurf, Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: +For clients such as Claude Desktop, Windsurf, and Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: [source,JSON] ---- From 1da13f094aafeb82ca7b1c5791449ed615210d0d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 22 Oct 2025 00:12:52 +0530 Subject: [PATCH 9/9] Update mcp-integration.adoc --- modules/ROOT/pages/mcp-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 8c3363407..d42224b5c 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -29,7 +29,7 @@ MCP tools are the actions that the MCP Server exposes to the agent for interacti * Ask natural language questions and get data in a structured format from ThoughtSpot * Retrieve relevant analytical questions based on user queries * Create a Liveboard with the answers generated from the queries -* Get data source recommendations based on a user's query and intent +//* Get data source recommendations based on a user's query and intent + Currently, the MCP Server supports the following tools: