The ThoughtSpot MCP Server provides secure OAuth-based authentication and a set of tools for querying and retrieving relevant data from your ThoughtSpot instance. It's a remote server hosted on Cloudflare.
If you do not have a Thoughtspot account, create one for free [here](https://thoughtspot.com/trial).
Learn more about [ThoughtSpot](https://thoughtspot.com).
Join our [Discord](https://developers.thoughtspot.com/join-discord) to get support.
See our privacy statement [here](https://www.thoughtspot.com/privacy-statement).
## Table of Contents
- [Connect](#connect)
- [Usage](#usage)
- [Demo video](#demo)
- [Usage Examples](#usage-examples)
- [Usage in APIs](#usage-in-apis)
- [OpenAI / ChatGPT](#openai-responses-api)
- [Claude](#claude-mcp-connector)
- [Gemini](#gemini-api)
- [Features](#features)
- [Supported transports](#supported-transports)
- [Manual client registration](#manual-client-registration)
- [Associating with a ThoughtSpot instance](#associate-with-a-thoughtspot-instance)
- [How to obtain a TS_AUTH_TOKEN](#how-to-obtain-a-ts_auth_token)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Local Development](#local-development)
- [Endpoints](#endpoints)
## Connect
As of May 1, 2026, the ThoughtSpot MCP Server supports Spotter 3, enabling advanced analytics, forecasting, multi-step reasoning, and deep research. The new MCP tools support real-time streaming and session-based conversations.
The server uses date-based versioning via the `?api-version=YYYY-MM-DD` query parameter. Appending this to your MCP server URL pins your integration to a specific version (or the closest earlier version if an exact match doesn't exist). Each new version may introduce new tools, enhancements, or bug fixes.
 OAuth apps (plug-and-play integrations for Claude, ChatGPT, or custom OAuth apps):
- https://agent.thoughtspot.app/mcp?api-version=latest — Always points to the latest version.
- https://agent.thoughtspot.app/mcp?api-version=YYYY-MM-DD — Pins to a specific version. Example: `?api-version=2026-04-30`.
- https://agent.thoughtspot.app/mcp — Not recommended. Currently points to the baseline version with legacy MCP tools.
 Bearer token apps (custom apps using bearer tokens):
- https://agent.thoughtspot.app/token/mcp — Always points to the latest version.
- https://agent.thoughtspot.app/token/mcp?api-version=YYYY-MM-DD — Pins to a specific version. Example: `?api-version=2026-04-30`.
To configure this MCP server in your MCP client (such as Claude Desktop, Windsurf, Cursor, etc.) which do not support remote MCPs, add the following configuration to your MCP client settings:
```json
{
"mcpServers": {
"ThoughtSpot": {
"command": "npx",
"args": [
"mcp-remote",
"https://agent.thoughtspot.app/mcp?api-version=latest"
]
}
}
}
```
See the [Troubleshooting](#troubleshooting) section for any errors / more details.
## Usage
1. Once the connection is done, ThoughtSpot datasources would show under the resources section.
2. Select a datasource (resource), to set the context of your query.
3. Now you could ask analytical questions, which claude can decide to use the relevant ThoughtSpot tools for.
See the video below for a complete demo.
## Demo
Here is a demo video using Claude Desktop.
https://github.com/user-attachments/assets/72a5383a-7b2a-4987-857a-b6218d7eea22
Watch on [Loom](https://www.loom.com/share/433988d98a7b41fb8df2239da014169a?sid=ef2032a2-6e9b-4902-bef0-57df5623963e)
## Usage Examples
The following examples show a single conversation that builds progressively,
starting from data discovery through to a finished Liveboard.
### Example 1: Find the right data source
**User prompt:** "What data sources are available for analyzing sales performance?"
**What happens:**
- Server searches available ThoughtSpot data sources and returns the most relevant
matches ranked by confidence score
- If the top two results are within 0.3 confidence of each other, the user is
prompted to pick one
- Otherwise, the highest confidence source is selected automatically
### Example 2: Explore top-selling products
**User prompt:** "What are my top selling products this year?"
**What happens:**
- Using the selected data source, the server decomposes the question
into sub-questions like "total sales by product ranked highest to lowest this year"
- Returns data with product names and sales figures, plus an inline chart
### Example 3: Build a multi-metric Liveboard
**User prompt:** "Create a Liveboard for me from the findings"
**What happens:**
- Using the generated answers, creates a named ThoughtSpot Liveboard with
all charts pinned and returns a link to the Liveboard
## Usage in APIs
ThoughtSpot's remote MCP server can be used in LLM APIs which support calling MCP tools.
Here are examples with the common LLM providers:
### OpenAI Responses API
```bash
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/token/mcp",
"headers": {
"Authorization": "Bearer $TS_AUTH_TOKEN",
"x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud"
}
}
],
"input": "How can I increase my sales ?"
}'
```
**Note**: Use `/token/mcp` for new integrations. The older `/bearer/mcp` endpoint is deprecated but still supported for backward compatibility.
More details on how can you use OpenAI API with MCP tool calling can be found [here](https://platform.openai.com/docs/guides/tools-remote-mcp).
### Claude MCP Connector
```bash
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/token/mcp",
"name": "thoughtspot",
"authorization_token": "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud"
}
]
}'
```
**Note**: In the `authorization_token` field we have suffixed the ThoughtSpot instance host as well with the `@` symbol to the `TS_AUTH_TOKEN`. Use `/token/mcp` for new integrations. The older `/bearer/mcp` endpoint is deprecated but still supported for backward compatibility.
More details on Claude MCP connector [here](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector).
### Gemini API
MCP tools can be used with the Gemini Python/Typescript SDK. Here is an example using typescript:
```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/token/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();
```
**Note**: Use `/token/mcp` for new integrations. The older `/bearer/mcp` endpoint is deprecated but still supported for backward compatibility.
Read [this](https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#mcp), for more details on Gemini API MCP tool calling.
An example using Google ADK + Python can be found [here](https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-google-adk-trusted-auth).
#### Gemini CLI extenstions
ThoughtSpot MCP server can also be installed as a Gemini CLI extension.
```bash
gemini extensions install https://github.com/thoughtspot/mcp-server
```
Read more about Gemini CLI [here](https://github.com/google-gemini/gemini-cli).
### How to get TS_AUTH_TOKEN for APIs ?
For API usage, you would the token endpoints with a `secret_key` to generate the `API_TOKEN` for a specific user/role, more details [here](https://developers.thoughtspot.com/docs/api-authv2#trusted-auth-v2).
## Features
- **OAuth Authentication**: Access your data, as yourself.
- Dynamic Client Registration (DCR) support.
- Any MCP host is allowed. Let's make the world fact driven.
- **Tools**:
- `ping`: Test connectivity and authentication.
- `getRelevantQuestions`: Get relevant data questions from ThoughtSpot analytics based on a user query.
- `getAnswer`: Get the answer to a specific question from ThoughtSpot analytics.
- `createLiveboard`: Create a liveboard from a list of answers.
- `getDataSourceSuggestions`: Get datasource suggestions for a given query.
- **MCP Resources**:
- `datasources`: List of ThoughtSpot Data models the user has access to.
### Supported transports
- SSE [https://agent.thoughtspot.app/sse]()
- Streamed HTTP [https://agent.thoughtspot.app/mcp]()
## Manual client registration
For MCP hosts which do not(yet) support Dynamic client registration, or they require statically adding Oauth Client Id etc. Go to [this](https://agent.thoughtspot.app/clients) page, to register a new client and copy the details over. The most relevant values are `Oauth Client Id` and `Oauth Client Secret` which should be added when adding ThoughtSpot as an MCP connector in the MCP client (ChatGPT/Claude etc). The generated client details are only available when they are generated and are NOT available later for reference.
### Associate with a ThoughtSpot instance
Manual client registration also allows to associate with a specific ThoughtSpot instance, so that your users do not have to enter the Thoughtspot instance URL when doing the authorization flow. While registering the Oauth client add `ThoughtSpot URL` to the appropriate value.
### How to obtain a `TS_AUTH_TOKEN` ?
- Go to ThoughtSpot => _Develop_ => _Rest Playground v2.0_
- _Authentication_ => _Get Full access token_
- Scroll down and expand the "body"
- Add your "username" and "password".
- Put whatever "validity_time" you want the token to be.
- Click on "Try it out" on the bottom right.
- You should get a token in the response, thats the bearer token.
#### Alternative way to get `TS_AUTH_TOKEN`
- Login to the ThoughtSpot instance as you would normally.
- Opem in a new tab this URL:
- https://your-ts-instance/api/rest/2.0/auth/session/token
- You will see a JSON response, copy the "token" value (without the quotes).
- This is the token you could use.
### Troubleshooting
> Oauth errors due to CORS/SAML.
Make sure to add the following entries in your ThoughtSpot instance:
*CORS*
- Go to ThoughtSpot => _Develop_ => Security settings
- Click "Edit"
- Add "agent.thoughtspot.app" to the the "CORS whitelisted domains".
*SAML* (need to be Admin)
- Go to ThoughtSpot => _Develop_
- Go to "All Orgs" Tab on the left panel if there is one.
- Click "Security settings"
- Click "Edit"
- Add "agent.thoughtspot.app" to the the "SAML redirect domains".
> MCP server install error due to node issues
- Make sure node is installed on your machine.
- Make sure the node version is >=18
- Check the node version by using the command `node -v`
> 500 error from MCP server
- Make sure the ThoughtSpot cluster the MCP server is connected to is up and running.
- If the error persists, please collect the logs that you get from the MCP client and the approximate time when the issue occurred.
- Reach out on [Discord](https://developers.thoughtspot.com/join-discord) to get support.
- Create a issue on this repository to get help.
- Submit a [ThoughtSpot support case](https://community.thoughtspot.com/s/article/How-to-submit-a-ThoughtSpot-Support-Case) with all the artifacts.
> Stale MCP auth
- If for some reason the ThoughtSpot MCP server is failing authentication repeatedly, you can do `rm -rf ~/.mcp-auth`.
- This will remove all stale authentication info, and restart the auth flow again.
## Contributing
### Local Development
1. **Install dependencies**:
```sh
npm install
```
2. **Set up environment variables**:
- Copy `.dev.vars` and fill in your ThoughtSpot instance URL and access token.
3. **Start the development server**:
```sh
npm run dev
```
### Adding New Tools
When adding new MCP tools to the server:
1. **Define schemas and tools** in `src/servers/tool-definitions.ts`
2. **Implement handlers** in `src/servers/mcp-server.ts`
3. **Update version registry** in `src/servers/version-registry.ts`:
- Add new tools to appropriate version(s) in `VERSION_REGISTRY`
- For new stable features, update `DEFAULT_VERSION`
- For beta features, add to the `beta` version entry
4. **Add tests** for new tools and version configurations
5. **Update documentation** in README.md
**Important:** The version registry controls which tools are available in each API version. Make sure to add new tools to the correct version configuration to ensure they're accessible to users.
### Endpoints
**OAuth-based endpoints:**
- `/mcp`: MCP HTTP Streaming endpoint (supports `?api-version`)
- `/sse`: Server-sent events for MCP (supports `?api-version`)
- `/authorize`, `/token`, `/register`: OAuth endpoints
**Token-based endpoints (Recommended for APIs):**
- `/token/mcp`: MCP HTTP Streaming with bearer auth (supports `?api-version`)
- `/token/sse`: Server-sent events with bearer auth (supports `?api-version`)
**Deprecated endpoints:**
- `/bearer/mcp`, `/bearer/sse`: Legacy MCP endpoints with bearer auth (**deprecated**, no `api-version` support). Use `/token/*` endpoints instead.
**API Versioning:**
The ThoughtSpot MCP Server supports API versioning to access different tool sets. You can specify the version using the `api-version` query parameter on OAuth and `/token/*` endpoints (not supported on deprecated `/bearer/*` endpoints).
**Version Formats:**
- **Beta version**: `?api-version=beta` - Access the latest beta features
- **Date-based version**: `?api-version=YYYY-MM-DD` - Access tools from a specific release date or the latest version on or before that date
- **Default** (no parameter): Returns the latest stable tool set
**Examples:**
```bash
# Beta version (latest experimental features)
https://agent.thoughtspot.app/token/mcp?api-version=beta
# Specific date version (Spotter 3 agent tools)
https://agent.thoughtspot.app/token/mcp?api-version=2026-05-01
# Date range resolution (returns newest version ≤ specified date)
https://agent.thoughtspot.app/token/mcp?api-version=2025-03-15
```
**Available Versions:**
- `beta`: Latest beta features with Spotter3 agent conversation tools
- `latest`: Most recent non-beta version
- `2026-05-01`: Spotter 3 agent conversation tools (`create_analysis_session`, `send_session_message`, `get_session_updates`)
- `2025-01-01`: Base MCP tools (`getRelevantQuestions`, `getAnswer`, `getDataSourceSuggestions`)
**Note:** The `/bearer/*` endpoints always return the default stable tool set and ignore the `api-version` parameter for backward compatibility.
MCP Server, © ThoughtSpot, Inc. 2025