MCP tool reference (Spotter 3)

The new ThoughtSpot MCP integration exposes a session-based workflow for running natural language analytics queries against your ThoughtSpot data sources. The pattern is always: create a session → send a message → poll for updates.

create_analysis_session🔗

Start an analytical session with ThoughtSpot’s analytics agent. This is the required first step before sending any questions.

Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling create_analysis_session again.

Input parameter🔗

The data_source_id is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question.

Example call🔗

const session = await callMCPTool("create_analysis_session", {
    data_source_id: "model-guid-123" // Optional — GUID of the ThoughtSpot worksheet or model to query. Omit to let ThoughtSpot automatically select the most relevant data source.
});

call_mcp_tool(
    "create_analysis_session",
    {
        "data_source_id": "model-guid-123"  # Optional — GUID of the ThoughtSpot worksheet or model to query.
    },
)

Response🔗

{
"analytical_session_id": "session-guid-abc123"
}

analytical_session_id: Session ID. Pass this to send_session_message and get_session_updates.
Always capture the returned analytical_session_id. It is required for all subsequent calls.

send_session_message🔗

Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use get_session_updates to retrieve the response.

Input parameters🔗

Field Description

Field	Description
`analytical_session_id`	The session to send the message to. Obtained from the `create_analysis_session` call.
`message`	A natural language analytical question or follow-up to send to the ThoughtSpot agent.
`additional_context` Optional	Can be used to provide external information relating to the question. For example, “The user’s fiscal year starts in April”, or “The user is a manager of the West region”.

analytical_session_id

The session to send the message to. Obtained from the create_analysis_session call.

message

A natural language analytical question or follow-up to send to the ThoughtSpot agent.

additional_context
Optional

Can be used to provide external information relating to the question. For example, “The user’s fiscal year starts in April”, or “The user is a manager of the West region”.

Example call🔗

const sendMessage = await callMCPTool("send_session_message", {
    analytical_session_id: "sess_abc123", // Session ID from create_analysis_session.
    message: "What were total sales by region last quarter?", // User's natural language question.
    additional_context: "The user's fiscal year starts in April. " +
        "Focus on underperforming regions only." // Optional — external information to influence the analysis.
});

call_mcp_tool(
    "send_session_message",
    {
        "analytical_session_id": "sess_abc123",  # Session ID from create_analysis_session.
        "message": "What were total sales by region last quarter?", # User's natural language question.
        "additional_context": (  # Optional — external information
            "The user's fiscal year starts in April."
            "Focus on underperforming regions only." # to influence the analysis.
        ),
    },
)

Response🔗

{
  "success": true
}

success: Confirms whether the message was successfully received by the agent.

Note

After a successful send, immediately begin polling with get_session_updates.
Do not send a second message until get_session_updates returns is_done: true. The agent processes one message at a time per session.
To ask a follow-up question, reuse the same analytical_session_id. There is no need to create a new session.

get_session_updates🔗

Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after send_session_message until is_done is true.

Important: A single call to get_session_updates will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture.

Input parameters🔗

Send the analytical_session_id to specify the session to retrieve updates for.

Example call🔗

const updates = await callMCPTool("get_session_updates", {
    analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call.
});

call_mcp_tool(
    "get_session_updates",
    {"analytical_session_id": "sess_abc123"},  # Session ID from create_analysis_session.
)

Response🔗

Poll returning intermediate updates with the "is_thinking" response:

{
  "is_done": false,
  "session_updates": [
    {
         "is_thinking":true,
         "type":"text_chunk",
         "text":"Let me look at your sales data by region...",
      },
  ]
}

Poll returning final updates:

{
   "is_done": true,
   "session_updates":[
      {
         "is_thinking":false,
         "type":"text-chunk",
         "text":"Data broken down by region..."
      },
      {
         "is_thinking":false,
         "type":"text",
         "text":"I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April."
      },
      {
         "is_thinking":false,
         "type":"answer",
         "answer_title":"Total Sales by Region — Q4 2025",
         "answer_query":"total sales by region last quarter",
         "iframe_url":"https://your-instance.thoughtspot.cloud/embed/...",
         "answer_id":"answer-guid-xyz789"
      }
   ]
}

Handling streamed responses🔗

Spotter queries are processed asynchronously and streamed in real time. This means the full response is never contained in a single get_session_updates call.

Each call to get_session_updates returns only the updates generated since the previous call. The session_updates array may indicate that Spotter is still processing with an is_thinking state, may include intermediate updates, or may contain several updates at once. Updates typically arrive as text or text-chunk types, reflecting Spotter’s ongoing reasoning, before the final answer update is provided. This intermediate content shows Spotter’s step-by-step thought process and should be preserved and presented to the user for transparency into how the answer is derived.

A typical response sequence might look like:

Thinking narration: text-chunk updates with is_thinking state describing what Spotter is doing.
Clarifications or caveats: text updates explaining assumptions, filters applied, or potential ambiguities in the question.
Intermediate conclusions: partial results or contextual notes before the final answer.
The final answer: one or more answer updates containing the visualization title, the underlying query, and the embeddable iframe URL.

This means a complete response might span between 5–20+ get_session_updates calls and contain many session_update objects before is_done becomes true. All of this content — the thinking, the narration, and the final answer — should be accumulated and presented together to give the user the full picture.

Type definition: session_update🔗

Each item in the session_updates list is a session_update object. The type field determines which other fields are present.

Field Type Description

Field	Type	Description
`type`	`"text"`	A complete natural language message from the agent.
`"text-chunk"`	A streaming chunk of a longer message. Concatenate all chunks to reconstruct the full text.
`"answer"`	Populates `answer_title`, `answer_query`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL.
`text`	String	The text content of the message. Present only when `type` is `"text"` or `"text-chunk"`. For `"text-chunk"` updates, concatenate all chunks in order to form the complete message.
`answer_title`	String	A human-readable title describing what the answer shows. Present only when `type` is `"answer"`.
`answer_query`	String	The search query ThoughtSpot used to generate the answer. Present only when `type` is `"answer"`. Useful for explaining to users what data was queried or for diagnosing unexpected results.
`iframe_url`	String	An embeddable URL for rendering the answer as an interactive visualization. Present only when `type` is `"answer"`. Use this to display a live chart or table if your environment supports iframes.

type

"text"

A complete natural language message from the agent.

"text-chunk"

A streaming chunk of a longer message. Concatenate all chunks to reconstruct the full text.

"answer"

Populates answer_title, answer_query, iframe_url fields. A data visualization result with a title, the underlying query, and an embeddable URL.

text

String

The text content of the message. Present only when type is "text" or "text-chunk". For "text-chunk" updates, concatenate all chunks in order to form the complete message.

answer_title

String

A human-readable title describing what the answer shows. Present only when type is "answer".

answer_query

String

The search query ThoughtSpot used to generate the answer. Present only when type is "answer". Useful for explaining to users what data was queried or for diagnosing unexpected results.

iframe_url

String

An embeddable URL for rendering the answer as an interactive visualization. Present only when type is "answer". Use this to display a live chart or table if your environment supports iframes.

create_dashboard🔗

Create a ThoughtSpot dashboard from answers generated in an analysis session.

Call this only after get_session_updates returns is_done: true, because you need the answer_id values from completed answer updates.
Collect all updates where type is answer across every poll of get_session_updates. Each one produces an answer_id you can include in the dashboard.
The note_tile should summarize the full analysis. It is the first thing a viewer sees on the dashboard.
Multiple answers from the same session or across multiple sessions can be combined into a single dashboard.

Input parameters🔗

Field Description

Field	Description
`title`	Required. Title of the dashboard to be created.
`answers`	Required. List of answer objects to add to the dashboard. Each answer requires an `answer_id` (from `get_session_updates` where `type` is `answer`) and a `title`.
`note_tile`	Required. An HTML summary of the analysis and answers, rendered as a styled tile on the dashboard. Must be a single line with no line breaks. Use `<br>` for spacing within the HTML. Include emojis, colors, and a `"Generated on <date> <time>"` header.

title

Required. Title of the dashboard to be created.

answers

Required. List of answer objects to add to the dashboard. Each answer requires an answer_id (from get_session_updates where type is answer) and a title.

note_tile

Required. An HTML summary of the analysis and answers, rendered as a styled tile on the dashboard. Must be a single line with no line breaks. Use <br> for spacing within the HTML. Include emojis, colors, and a "Generated on <date> <time>" header.

Example call🔗

const dashboard = await callMCPTool("create_dashboard", {
    title: "Q4 2025 Regional Sales Analysis",
    answers: [{
            answer_id: "ans_xyz789", // answer_id from each answer-type update returned by get_session_updates.
            title: "Total Sales by Region — Q4 2025"
        },
        {
            answer_id: "ans_xyz790",
            title: "Underperforming Regions — Q4 2025 vs Q4 2024"
        }
    ],
    note_tile: "<h2 style='text-align:center;'> Q4 2025 Regional Sales Analysis</h2>" +
        "<p>Analysis of total sales by region for Q4 2025, highlighting " +
        "top-performing and underperforming regions.<br>" +
        "Generated on 2026-04-16 10:00 AM</p>" // Required — single-line HTML string rendered as a styled summary tile at the top of the dashboard.
});

dashboard = call_mcp_tool(
    "create_dashboard",
    {
        "title": "Q4 2025 Regional Sales Analysis",
        "answers": [
            {
                "answer_id": "ans_xyz789", # answer_id from each answer-type update returned by get_session_updates.
                "title": "Total Sales by Region — Q4 2025",
            },
            {
                "answer_id": "ans_xyz790",
                "title": "Underperforming Regions — Q4 2025 vs Q4 2024",
            },
        ],
        "note_tile": (
            "<h2 style='text-align:center;'> Q4 2025 Regional Sales Analysis</h2>"
            "<p>Analysis of total sales by region for Q4 2025, highlighting "
            "top-performing and underperforming regions.<br>"
            "Generated on 2026-04-16 10:00 AM</p>"  # Required. single-line HTML string rendered as a styled summary tile at the top of the dashboard.
        ),
    },
)

Response🔗

Field Description

Field	Description
`dashboard_id`	The unique identifier of the created dashboard.
`dashboard_url`	A link to the newly created dashboard in ThoughtSpot.

dashboard_id

The unique identifier of the created dashboard.

dashboard_url

A link to the newly created dashboard in ThoughtSpot.

Visualizations embedded in iframe🔗

When displaying the embedded visualization using the iframe_url property, the following user interaction features are included by default:

Area Option Visibility

Area	Option	Visibility
Primary actions and actions in the More (`…`) options menu	Pin	Visible
Save	Visible
Download	Visible
Edit	Not visible
Add to Coaching	Not visible
Context menu actions	Aggregate	Visible
Filter	Visible
Sort	Visible
Position	Visible
Conditional formatting	Not visible
Rename	Not visible
Edit	Not visible
Remove	Not visible
Axis menu	Exclude	Visible
Only include	Visible
Drill down	Visible
Show underlying data	Visible

Primary actions and actions in the More (…) options menu

Pin

Visible

Save

Visible

Download

Visible

Edit

Not visible

Add to Coaching

Not visible

Context menu actions

Aggregate

Visible

Filter

Visible

Sort

Visible

Position

Visible

Conditional formatting

Not visible

Rename

Not visible

Edit

Not visible

Remove

Not visible

Axis menu

Exclude

Visible

Only include

Visible

Drill down

Visible

Show underlying data

Visible

The following features are not supported directly. However, you can use the Make a Copy option to access these capabilities:

Drill down
Changing filters
Changing chart type or chart configuration
Show underlying data, view query SQL or query visualizer
SpotIQ analysis

Additional resources🔗

For a chat client example, see Python Agent with Simple React UI.
For information about rendering iframe visualizations, see the startAutoMCPFrameRenderer function reference.