Skip to content

main-rel sync #364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ShashiSubramanya merged 17 commits into from
Oct 8, 2025
Merged

main-rel sync #364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
12a948f
theme builder updates
rani2655 Sep 23, 2025
e4c74c6
theme builder updates1
rani2655 Sep 24, 2025
d396b63
theme builder updates2
rani2655 Sep 24, 2025
ed1d9fc
feedback edits
rani2655 Sep 29, 2025
157bdc1
link fix
ShashiSubramanya Oct 3, 2025
777bb16
rt-filters-params
ShashiSubramanya Oct 3, 2025
7eec368
image udpate
ShashiSubramanya Oct 3, 2025
8256a45
edits
ShashiSubramanya Oct 6, 2025
58e1231
edits
ShashiSubramanya Oct 6, 2025
c66cd1e
typo fix
ShashiSubramanya Oct 6, 2025
878bbc1
updated theme builder url
ruchI9897 Oct 8, 2025
9380af9
Theme builder changes
rani2655 Oct 8, 2025
0651bd7
reverting beta changes
ruchI9897 Oct 8, 2025
cdf5be7
reverting beta changes
ruchI9897 Oct 8, 2025
56b5568
Theme builder changes1
rani2655 Oct 8, 2025
f35fdeb
Merge pull request #362 from thoughtspot/SCAL-276581
ruchI9897 Oct 8, 2025
59cc173
Merge pull request #363 from thoughtspot/theme-builder
rani2655 Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions modules/ROOT/pages/developer-playground.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ You can explore the following SDK components in the Playground.
* xref:developer-playground.adoc#playground-visualization[Visualizations]
* xref:developer-playground.adoc#playground-fullapp[Full application]


[#playground-search]
== Search
To explore the Search embed function:
Expand Down Expand Up @@ -215,6 +214,10 @@ searchOptions: {
}
----

a|**Set runtime filters and parameters** +

include::{path}/set-runtime-overrides.adoc[]

a|**Modify available actions** +

include::{path}/modify-available-actions.adoc[]
Expand All @@ -234,7 +237,6 @@ For more information about CSS variables, styles, and customizations options, se
|
|====


[#playground-visualization]
== Visualization
To explore the visualization embedding function:
Expand Down
16 changes: 8 additions & 8 deletions modules/ROOT/pages/embed-ai-analytics.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,21 @@
:page-pageid: embed-ai-search-analytics
:page-description: To embed ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK library.

ThoughtSpot Spotter provides an interactive AI-powered Search and conversation analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis.
ThoughtSpot Spotter provides an interactive AI-powered Search and conversational analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis.

== Embed components
For embedding applications, ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in their app:
ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in your app:

* xref:embed-spotter.adoc[`SpotterEmbed`] +
To embed the full Spotter interface with a conversation panel that allows natural language text strings, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component.
To embed the full Spotter interface with a conversation panel that allows natural language queries, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component.
For more information, see xref:embed-spotter.adoc[Embed Spotter].
* xref:embed-spotter-agent.adoc[`SpotterAgentEmbed`] +
The Spotter Agent embedding, also known as `bodyless` embed, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over the look and feel and workflow of the embedded analytics experience. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations.
The Spotter Agent embedding, also known as `bodyless` embedding, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over user experience and workflow of embedded analytics. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations.

[NOTE]
====
* The `ConversationEmbed` and `BodylessConversation` components are deprecated and replaced with `SpotterEmbed` and `SpotterAgentEmbed` respectively in Visual Embed SDK v1.38.0 and later.
* If you are embedding full ThoughtSpot experience in your app via `AppEmbed`, you must enable new home page experience and set the home page search bar mode to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding].
* If you are embedding the full ThoughtSpot experience in your app via `AppEmbed`, you must set the search bar mode on the home page to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding].
====

== Spotter embed and Spotted Agent embed comparison
Expand Down Expand Up @@ -58,11 +58,11 @@ a| * Supported data object is Model

== Customization options in the SDK

Visual Embed SDK provides several view configuration settings and customization options for customizing Spotter embeds:
Visual Embed SDK provides several configuration settings and controls for customizing Spotter embed view:

* Configuration properties to enable or disable features.
* Configuration properties that enable or disable features.
For more information, see xref:_spotterembedviewconfig.adoc[SpotterEmbedViewConfig] and xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig]
* Action customization framework to show or hide actions in the embedded view +
* The action customization framework to show or hide actions in the embedded view +
For more information, see xref:Action.adoc[Action] and xref:embed-action-ref.adoc[Action IDs in the SDK]
* Event handlers for host and embed app interaction +
For more information, see xref:EmbedEvent.adoc[Embed events], xref:HostEvent.adoc[Host events], and xref:embed-events.adoc[Events and app interactions]
Expand Down
72 changes: 36 additions & 36 deletions modules/ROOT/pages/mcp-integration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
= Agentic MCP server integration
= MCP server integration
:toc: true
:toclevels: 3

:page-title: MCP integration
: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 allows 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 to interact with ThoughtSpot’s data and its analytics capabilities programmatically.
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.

The MCP tools of the Agentic MCP Server support the following functions:

Expand All @@ -17,40 +17,40 @@ The MCP tools of the Agentic MCP Server support the following functions:

== Integration overview

The Agentic MCP server integration requires the following core components and authentication framework:
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.
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.

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 are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP Server supports the following tools:

* `ping` to test connection to ThoughtSpot
* `getRelevantQuestions` to get relevant analytical questions +
The `getRelevantQuestions` tool calls `/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 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.
* `getAnswer` to execute the queries and fetch data +
The `getAnswer` tool calls `/api/rest/2.0/ai/agent/converse/sse` API and generates answers and insights for a given data context.
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.
* `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 data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources.
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.
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.

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. +
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
* 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.
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.
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

Expand All @@ -59,46 +59,46 @@ When the MCP Server integration is enabled, your host app connects to ThoughtSpo
. 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 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 and presents it to the user
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 following figure illustrates the sequence of workflows in a typical MCP server integration setup:
The following figure illustrates the sequence of workflows in a typical MCP Server integration setup:

[.widthAuto]
image::./images/mcp-integration.png[MCP integration]

== Get started with the integration
To get started with the integration, complete the steps described in the following sections. In this article, we'll integrate ThoughtSpot MCP server with Claude and enable agentic interaction and workflows.
== Get started
To get started with the integration, complete the steps described in the following sections. In this article, we'll integrate ThoughtSpot MCP Server with Claude and enable agentic interaction and workflows.

=== Before you begin

Before you begin, verify if your application setup has the following:

* Node.js version 22 or later is installed on your system.
* Node.js version 22 or later is installed.
* A ThoughtSpot instance with 10.11.0.cl or later release version. You'll need administrator credentials to configure security settings or set up token-based authentication for your application users.
* Your application users require at least view access to the data source objects to query data and get answers.
* 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.

=== Configure security settings on ThoughtSpot

To allow the secure communication between the MCP server and your ThoughtSpot instance, configure the following settings:
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.
. 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.

=== Add MCP server to the MCP client's config
=== Add MCP Server to the MCP client's config

If your MCP client supports remote MCP servers, add the MCP server URL to the client's config file.
If your MCP client supports remote MCP Servers, add the MCP Server URL to the client's config file.

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:
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:

[source,JSON]
----
Expand All @@ -118,10 +118,10 @@ MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote M

After updating the config file:

. Connect to ThoughtSpot instance and complete authentication.
. 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 add data context from ThoughtSpot. +
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]
Expand All @@ -140,7 +140,7 @@ You can adjust tool access, resources, instructions to data models, object permi

=== Verify the query and response workflow

* Select a datasource to set the context of your query. +
* Select a data source to set the context of your query. +
For example, on Claude Desktop, click the `+` icon and select a data source.

+
Expand Down Expand Up @@ -170,18 +170,18 @@ image::./images/create-lb-claude.png[Liveboard creation]

== Configuration considerations and best practices

* Users must have access to the data source. If not, it will lead to empty results.
* Users must have at least view access to the data source. Otherwise, it may lead to empty results.
* Ensure that data is modeled. Large or complex data sources may impact response time.
* Streaming responses require client support for real-time updates. Ensure that the system is available.
* Streaming responses require client support for real-time updates. Ensure that your system is available to receive and process data.
* Each conversation is session-based. Ensure that session IDs are managed correctly in your integration.

== Additional resources

* 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.
* 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:

** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation]
** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation]
** xref:spotter-apis.adoc[Spotter AI APIs]
* In case of issues with connection or authentication, check the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]
* 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^].
Loading
Loading