Connect ThoughtSpot to Claude: Automate Data Models and Git Sync

If your team uses ChatGPT, check out our guide on /connect-thoughtspot-to-chatgpt-manage-users-roles-and-ai-spotter/ or explore our broader architectural overview on /connect-thoughtspot-to-ai-agents-query-data-and-export-reports/.

Giving a Large Language Model (LLM) read and write access to a sprawling business intelligence platform like ThoughtSpot requires significant integration middleware. You need to manage complex authentication lifecycles, map massive JSON schemas to tool definitions, and handle specific domain logic around the ThoughtSpot Modeling Language (TML). You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated Model Context Protocol (MCP) server.

This guide breaks down exactly how to use Truto to generate a secure MCP server for ThoughtSpot, connect it natively to Claude Desktop, and execute complex data operations using natural language.

The Engineering Reality of the ThoughtSpot API

Building a custom MCP server means you own the entire integration lifecycle. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. ThoughtSpot is built to manage massive data models, cross-org publishing, and AI-driven conversational querying (Spotter). Its API reflects that deep complexity.

If you decide to build a custom ThoughtSpot MCP server, here are the specific integration challenges you will face:

TML and Asynchronous Operations ThoughtSpot relies heavily on TML (ThoughtSpot Modeling Language) to represent metadata objects like Liveboards, Answers, and Worksheets. Importing or exporting these objects often requires asynchronous batch jobs. An LLM cannot inherently manage long-running async tasks. If Claude tells an MCP server to import a complex TML file, your server must schedule the import, poll the /api/rest/2.0/metadata/tml/async/status endpoint, and only return a result to Claude when the job completes.

Cross-Org Identifiers and GUID Resolution ThoughtSpot supports multi-tenant organizations within a single cluster. When interacting with APIs like version control or metadata publishing, objects must be referenced by cross-Org object IDs rather than simple names. An LLM lacks the context to resolve a human-readable string like "Q3 Sales Liveboard" to a cross-Org GUID. Your integration layer must handle the lookup and mapping before executing the core request, otherwise the ThoughtSpot API will reject the payload.

Strict Rate Limiting and Backoff Delegation Like any enterprise system, ThoughtSpot enforces strict concurrency and rate limits on its endpoints. When a limit is breached, the API returns an HTTP 429 Too Many Requests response. It is a critical architectural decision not to hide these errors from the caller. Truto's managed MCP server normalizes the upstream rate limit data into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification, but it does not automatically retry or apply exponential backoff. The HTTP 429 error is passed directly back to Claude. This ensures the LLM orchestration layer retains complete control over retry logic and state, rather than hanging indefinitely on a hidden server-side retry loop.

Step 1: Generating the ThoughtSpot MCP Server

Rather than hand-coding tool definitions for ThoughtSpot's massive API surface, Truto dynamically derives them from documentation records and resource configurations. This ensures that every tool exposed to Claude is fully documented with strict JSON schemas for both query parameters and request bodies.

You can generate an MCP server for a connected ThoughtSpot account using either the Truto UI or the API.

Method A: Via the Truto UI

This is the fastest method for manual testing and internal administration.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your active ThoughtSpot connection.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can restrict the server to specific tags (e.g., "metadata", "spotter") or specific methods (e.g., "read" only).
6. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6....

Method B: Via the API

For production deployments where you need to programmatically spin up MCP servers for different tenants or automated pipelines, use the Truto API. This allows you to enforce strict access controls on the fly.

Endpoint: POST /integrated-account/:id/mcp

{
  "name": "ThoughtSpot Data Modeling Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["metadata", "version_control", "spotter"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

The API provisions a secure token, links it to the specific ThoughtSpot integrated account, and returns the endpoint URL. All tools are generated dynamically at runtime when Claude calls the tools/list endpoint.

Step 2: Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, connecting it to Claude is a one-step process. Because the URL contains a cryptographically hashed token that routes to your specific ThoughtSpot instance, no additional OAuth configuration is needed on the client side.

Method A: Via the Claude UI (or ChatGPT)

If you are using a modern web interface that supports remote MCP connections:

For Claude:

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server.
3. Paste your Truto MCP URL into the connection field.
4. Click Add. Claude will instantly execute a handshake, pull the available ThoughtSpot tools, and prepare them for your prompt.

For ChatGPT:

1. Navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle.
3. Under MCP servers / Custom connectors, click add.
4. Provide a name (e.g., "ThoughtSpot via Truto") and paste the Truto MCP URL.

Method B: Via Manual Config File (Claude Desktop)

If you are running Claude Desktop or a custom LangGraph framework, you connect via Server-Sent Events (SSE) using the official MCP CLI transport.

Edit your claude_desktop_config.json file:

{
  "mcpServers": {
    "thoughtspot-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the connection, and Claude will now have direct, schema-validated access to ThoughtSpot.

Hero Tools for ThoughtSpot Operations

When Claude connects to the ThoughtSpot MCP server, it gains access to dozens of curated endpoints. Truto merges query parameters and body schemas into a single flat input namespace, making it incredibly easy for the LLM to construct valid payloads.

Here are the highest-leverage tools for automating ThoughtSpot workflows.

Execute Git Commits for Data Models

Tool: create_a_thought_spot_version_control_commit

Starts a versioning run that exports specified metadata objects (like Liveboards and Answers) and commits their TML representations to the Git branch configured for your Org.

"I updated the Q3 Revenue Liveboard. Please commit the changes to our configured Git repository with the comment 'Added regional breakdown charts' and target the specific object GUID."

Query Spotter AI for Analytics

Tool: thought_spot_agent_conversations_v_2_send

Sends a natural language query to Spotter (ThoughtSpot's AI agent) and returns the complete analytical response synchronously. Requires an active conversation identifier.

"Use Spotter to analyze our current sales data. Send the message 'What were the top three performing product categories last month?' to conversation ID 8f7e6d5c and return the visualization type and display tokens."

Cross-Org Metadata Publishing

Tool: create_a_thought_spot_metadata_publish

Publishes Liveboards, Answers, and Logical Tables across organizations in ThoughtSpot, sharing the objects along with their dependencies to the admins of the target orgs.

"Take the new Marketing KPI Liveboard (GUID 12345) and publish it across to the EMEA Organization (GUID 67890). Ensure dependencies are included."

Generate Single AI Answers

Tool: create_a_thought_spot_answer_create

Generates a single AI answer for a natural language query against a specific ThoughtSpot data model, bypassing the need for a persistent conversation session.

"Run a single query against the Global Finance data model to find 'Total OPEX by department for Q2'. Return the raw answer details and tokens."

Provision ThoughtSpot Users

Tool: create_a_thought_spot_user

Creates a new user record in ThoughtSpot, setting their display name, email, and assigning them to specific user groups.

"Create a new ThoughtSpot user for Jane Doe (jane.doe@company.com). Set her display name to 'Jane Doe - Analytics' and assign her to the 'Data Analysts' group."

Configure Cluster Authentication

Tool: create_a_thought_spot_auth_configure

Enables or disables Trusted Authentication (TRUSTED_AUTH) at the cluster level or for specific Organizations.

"Enable trusted authentication for our cluster preferences to support our new embedding application. Make sure the auth type is set to TRUSTED_AUTH."

For the complete list of available ThoughtSpot tools, including robust schemas for TML imports, system configuration, and data source management, view the ThoughtSpot integration page.

Workflows in Action

Exposing individual tools is useful, but the real power of an MCP server is enabling Claude to autonomously orchestrate multi-step data workflows. Here are two real-world examples.

Workflow 1: Automated TML Version Control

Data engineers need to maintain strict version control over ThoughtSpot data models. Instead of manually exporting TML files and committing them to Git, Claude can handle the entire sync pipeline.

"We just finalized the changes to the 'Enterprise Sales Pipeline' model. Please find its object ID, validate the target branch in our Git integration, and execute a commit with the message 'Q4 Sales Pipeline updates'."

1. list_all_thought_spot_search_2_0_metadata: Claude searches the metadata directory to locate the exact GUID for the "Enterprise Sales Pipeline" model.
2. list_all_thought_spot_version_control_configs: Claude retrieves the Org's active version control configuration to verify the target repository and branch.
3. create_a_thought_spot_version_control_commit: Claude executes the commit, targeting the resolved GUID and pushing the TML to the remote Git branch.

sequenceDiagram
    participant Claude as Claude
    participant MCP as Truto MCP Server
    participant Upstream as Upstream API (ThoughtSpot)

    Claude->>MCP: call tool list_all_thought_spot_search_2_0_metadata
    MCP->>Upstream: GET /api/rest/2.0/metadata/search
    Upstream-->>MCP: [Returns object GUIDs]
    MCP-->>Claude: JSON array of metadata objects
    Claude->>MCP: call tool create_a_thought_spot_version_control_commit
    MCP->>Upstream: POST /api/rest/2.0/vcs/commits
    Upstream-->>MCP: { "run_id": "9a8b..." }
    MCP-->>Claude: Commit executed successfully

Workflow 2: Cross-Org Publishing and Access Provisioning

When a central analytics team builds a new dashboard, IT admins must publish it to regional organizations and ensure the right users have access.

"Publish the 'Global Supply Chain' Liveboard to the APAC organization. Once published, create a new user account for the APAC director (chen@company.com) and assign them to the regional viewers group."

1. create_a_thought_spot_metadata_publish: Claude pushes the Liveboard and its underlying data dependencies from the central cluster to the APAC organization.
2. create_a_thought_spot_user: Claude provisions the new user account for the director.
3. update_a_thought_spot_user_group_by_id: Claude updates the regional viewers group to include the newly created user ID, ensuring immediate access to the published dashboard.

Security and Access Control

When granting LLMs access to enterprise BI platforms, security is paramount. Truto provides several mechanisms to lock down your ThoughtSpot MCP server:

• Method Filtering: Enforce strict operation boundaries. Setting methods: ["read"] ensures Claude can only execute GET or LIST commands, preventing accidental data deletion or unauthorized metadata publishing.
• Tag Filtering: Scope tools by functional domain. By applying a tag filter like ["spotter", "metadata"], you prevent the LLM from accessing unrelated administrative tools like user provisioning or security settings.
• Time-to-Live (TTL): Use the expires_at field to create ephemeral MCP servers. This is ideal for CI/CD pipelines or temporary contractor access, as the server self-destructs (cleaning up KV storage and database records) when the TTL expires.
• Dual-Layer Authentication: Enable require_api_token_auth to force the MCP client to send a valid Truto API token in the Authorization header. This ensures that mere possession of the MCP URL is not enough to execute ThoughtSpot API calls.

Wrapping Up

Integrating AI agents with ThoughtSpot requires more than just passing an API key. You must handle complex metadata resolution, manage asynchronous TML syncs, and respect strict rate limits. By leveraging Truto's managed MCP server, you offload the entire integration layer. You get dynamic, documentation-driven tools that are always up to date, allowing your AI agents to seamlessly query Spotter, manage data models, and control Git versioning using natural language.