ThoughtSpot MCP Server

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.

Learn more about ThoughtSpot.

Join our Discord to get support.

Connect

If using a client which supports remote MCPs natively (Claude.ai etc) then just enter:

MCP Server URL:

https://agent.thoughtspot.app/mcp

Preferred Auth method: Oauth

For OpenAI ChatGPT Deep Research, add the URL as:

https://agent.thoughtspot.app/openai/mcp

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:

{
  "mcpServers": {
    "ThoughtSpot": {
      "command": "npx",
      "args": [
         "mcp-remote",
         "https://agent.thoughtspot.app/mcp"
      ]
    }
  }
}

See the Troubleshooting section for any errors / more details.

Usage

Once the connection is done, ThoughtSpot datasources would show under the resources section.
Select a datasource (resource), to set the context of your query.
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.

ThoughtSpot-MCP-server-demo.mp4

Watch on Loom

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

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.

Claude MCP Connector

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.

Gemini API

MCP tools can be used with the Gemini Python/Typescript SDK. Here is an example using 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, for more details on Gemini API MCP tool calling.

An example using Google ADK + Python can be found here.

Gemini CLI extenstions

ThoughtSpot MCP server can also be installed as a Gemini CLI extension.

gemini extensions install https://github.com/thoughtspot/mcp-server

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.

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 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 to get support.
Create a issue on this repository to get help.
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

Install dependencies:
```
npm install
```
Set up environment variables:
- Copy .dev.vars and fill in your ThoughtSpot instance URL and access token.
Start the development server:
```
npm run dev
```

Adding New Tools

When adding new MCP tools to the server:

Define schemas and tools in src/servers/tool-definitions.ts
Implement handlers in src/servers/mcp-server.ts
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
Add tests for new tools and version configurations
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)
/api: MCP tools exposed as HTTP endpoints
/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 stable default tool set

Examples:

# Beta version (latest experimental features)
https://agent.thoughtspot.app/token/mcp?api-version=beta

# Specific date version (Spotter3 agent tools)
https://agent.thoughtspot.app/token/mcp?api-version=2025-03-01

# Date range resolution (returns latest version ≤ specified date)
https://agent.thoughtspot.app/token/mcp?api-version=2025-03-15

# Default version (stable tools)
https://agent.thoughtspot.app/token/mcp

Available Versions:

beta: Latest beta features with Spotter3 agent conversation tools
2025-03-01: Spotter3 agent conversation tools (createConversation, sendConversationMessage, getConversationUpdates)
2024-12-01: Base MCP tools (getRelevantQuestions, getAnswer, getDataSourceSuggestions)
default: Stable base tools (same as 2024-12-01)

Note: The /bearer/* endpoints always return the default stable tool set and ignore the api-version parameter for backward compatibility.

Name		Name	Last commit message	Last commit date
Latest commit History 143 Commits
.github/workflows		.github/workflows
deploy		deploy
public		public
scripts		scripts
src		src
static		static
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
biome.json		biome.json
gemini-extension.json		gemini-extension.json
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
server.schema.json		server.schema.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
worker-configuration.d.ts		worker-configuration.d.ts
wrangler.jsonc		wrangler.jsonc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ThoughtSpot MCP Server

Table of Contents

Connect

Usage

Demo

Usage in APIs

OpenAI Responses API

Claude MCP Connector

Gemini API

Gemini CLI extenstions

How to get TS_AUTH_TOKEN for APIs ?

Features

Supported transports

Manual client registration

Associate with a ThoughtSpot instance

How to obtain a `TS_AUTH_TOKEN` ?

Alternative way to get `TS_AUTH_TOKEN`

Troubleshooting

Contributing

Local Development

Adding New Tools

Endpoints

About

Uh oh!

Uh oh!

Contributors 4

Languages

Folders and files

Latest commit

History

Repository files navigation

ThoughtSpot MCP Server

Table of Contents

Connect

Usage

Demo

Usage in APIs

OpenAI Responses API

Claude MCP Connector

Gemini API

Gemini CLI extenstions

How to get TS_AUTH_TOKEN for APIs ?

Features

Supported transports

Manual client registration

Associate with a ThoughtSpot instance

How to obtain a TS_AUTH_TOKEN ?

Alternative way to get TS_AUTH_TOKEN

Troubleshooting

Contributing

Local Development

Adding New Tools

Endpoints

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Uh oh!

Contributors 4

Languages

How to obtain a `TS_AUTH_TOKEN` ?

Alternative way to get `TS_AUTH_TOKEN`