From 67988f3a633ce08ee86271d2ac904dfe500369c2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 3 Nov 2026 16:11:47 +0530 Subject: [PATCH 1/4] SCAL-349346 - MCP tools --- modules/ROOT/pages/mcp-integration.adoc | 3 + modules/ROOT/pages/mcp-server-changelog.adoc | 51 ++ modules/ROOT/pages/mcp-server-spotter3.adoc | 17 +- .../pages/mcp-tool-reference-spotter3.adoc | 803 ++++++++++++++++-- 4 files changed, 817 insertions(+), 57 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 942542efe..8101392f4 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -14,8 +14,11 @@ ThoughtSpot Spotter MCP Server exposes ThoughtSpot analytics as tools and resour * Automatic discovery of ThoughtSpot MCP tools * Natural language queries and responses * Programmatic creation of Liveboards and visualizations +* Changing existing dashboards, such as rearranging, restyling, and adding charts, text, groups, and tabs * Generating embeddable visualizations * Searching for existing ThoughtSpot content by name, author, tag, or type +* Reading the data behind existing Answers and Liveboards +* Building and editing data models through conversation === Supported integrations ThoughtSpot Spotter MCP Server supports two primary integration options: diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 5c01d63ef..b16f6d773 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -24,6 +24,57 @@ This changelog lists the new features, enhancements, and other changes introduce // *Affects:* Developers, Administrators, End Users // ============================================================ +== October 2026 +// TODO: verify with engineering. Confirm the upgrade behavior of unpinned URLs. +*API version string:* `?api-version=latest` + +*Upgrade notes*: Existing integrations using `?api-version=latest` receive these changes automatically. The `create_dashboard` changes may break integrations that read its response. See xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. + +[.cl-table, cols="1,4", frame=none, grid=none] +|==== +a| +[.cl-label] + +*October 2026* + +a| + +[discrete] +==== `create_dashboard` MCP tool [.version-badge.breaking]#Breaking# +The `create_dashboard` tool is now powered by SpotterViz. It can create a dashboard from completed analysis or from a description. SpotterViz shares its plan and chosen data source first, and nothing is built until the user approves. + +* The response is a status object. The tool can return `completed`, `in_progress`, `needs_input`, or `failed`. +* The `note_tile` parameter is removed. +* The `answers` parameter is now optional. +* The `instructions`, `task_id`, and `data_source_id` parameters are added. + +For more information, see xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. + +--- + +[discrete] +==== `modify_dashboard` MCP tool +The new `modify_dashboard` MCP tool changes an existing dashboard. It can rearrange and restyle content, add charts and explanatory text, and organize charts into groups and tabs. For more information, see xref:mcp-tool-reference-spotter3.adoc#modify_dashboard[modify_dashboard]. + +--- + +[discrete] +==== `get_dashboard_status` MCP tool +The new `get_dashboard_status` MCP tool polls a dashboard task that `create_dashboard` or `modify_dashboard` left in progress. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_dashboard_status[get_dashboard_status]. + +--- + +[discrete] +==== `get_data` MCP tool +The new `get_data` MCP tool fetches the columns and rows of a saved Answer or Liveboard. Use it with `search_objects` to answer questions from content that your organization already trusts. The tool is available only to users who have the privilege to download data. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_data[get_data]. + +--- + +[discrete] +==== Model builder MCP tools +The new model builder MCP tools let agents build a data model from warehouse tables, or edit an existing model, through conversation. The tools are `create_model_session`, `send_model_message`, `get_model_updates`, and `finalize_model`. The builder proposes a plan for approval, and the model is saved only after the user confirms. The tools are available only to users who can create or edit data models. For more information, see xref:mcp-tool-reference-spotter3.adoc#model-builder-tools[Model builder tools]. + +|==== + == August 2026 *API version string:* `?api-version=2026-05-01` + *Upgrade notes*: Existing integrations using `?api-version=2026-05-01` or `?api-version=latest` will be automatically upgraded. diff --git a/modules/ROOT/pages/mcp-server-spotter3.adoc b/modules/ROOT/pages/mcp-server-spotter3.adoc index fe03bf9c8..c5543109f 100644 --- a/modules/ROOT/pages/mcp-server-spotter3.adoc +++ b/modules/ROOT/pages/mcp-server-spotter3.adoc @@ -83,9 +83,8 @@ ThoughtSpot returns the following update types: //// 5. *User generates a dashboard with the results (optional)* + -The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. + -ThoughtSpot creates a dashboard and returns a `dashboard_id` and a -`dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. +The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. The agent passes each `answer_title` as the `title` of the answer, and can add `instructions` for layout and style. + +SpotterViz, the ThoughtSpot dashboard designer, organizes and styles the charts and saves them as a dashboard. If the dashboard is not ready, `create_dashboard` returns `status: "in_progress"` and a `task_id`, and the agent polls `get_dashboard_status` until the status changes. When the status is `completed`, the response contains the `dashboard_id` and the `dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. For more information, see xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. The other optional tool calls include: @@ -98,6 +97,18 @@ If the user belongs to more than one Org and connects over OAuth, the agent call * *Agent searches for existing content (optional)* + If the user refers to content that already exists, for example, "open the regional sales Liveboard", the agent calls `search_objects` with a search term and optional filters such as object type, author, tag, or verified status. `search_objects` returns a ranked list of matching objects with their metadata and deep links. +* *Agent reads the data behind existing content (optional)* + +After `search_objects` returns an Answer or Liveboard, the agent can call `get_data` with the `object_id` from the result, and the result's `type` as `object_type`, to fetch the columns and rows that the object shows. For a single visualization on a Liveboard, the agent passes the `visualization_id` in `visualization_ids`. The agent answers from the returned rows, which reflect the latest data. `get_data` is available only to users who have the privilege to download data. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_data[get_data]. + +* *User asks for a dashboard from a description (optional)* + +If the user asks for a dashboard before any analysis, or wants one recreated from another tool, the agent calls `create_dashboard` with `instructions` and no `answers`. SpotterViz returns `status: "needs_input"` with the data source it chose and its plan. The agent shows the plan to the user. After the user confirms or asks for changes, the agent calls `create_dashboard` again with the same `task_id` and the user's reply in `instructions`. + +* *User changes an existing dashboard (optional)* + +The agent finds the dashboard GUID with `search_objects`, and calls `modify_dashboard` with the `dashboard_id` and the user's change in `instructions`. If SpotterViz asks a question, the agent shows it to the user and calls `modify_dashboard` again with the same `dashboard_id` and `task_id`. For more information, see xref:mcp-tool-reference-spotter3.adoc#modify_dashboard[modify_dashboard]. + +* *User builds or edits a data model (optional)* + +The agent calls `create_model_session` with a connection GUID for a new model, or a model GUID to edit one. The agent sends instructions with `send_model_message` and polls `get_model_updates` until `is_done` is `true`. The builder proposes a plan first, and the agent shows it to the user and waits for approval. To save, the agent calls `finalize_model` for a summary, and then calls it again with `confirm: true` after the user approves. The model builder tools are available only to users who can create or edit data models. For more information, see xref:mcp-tool-reference-spotter3.adoc#model-builder-tools[Model builder tools]. + == Additional resources * For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. * For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index d2f2e6822..0b1a334d8 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -1,3 +1,4 @@ + = MCP tool reference (Spotter 3) :toc: true :toclevels: 3 @@ -6,7 +7,8 @@ :page-pageid: mcp-tool-reference-spotter3 :page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. -The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes tools for running natural language analytics queries and searching existing ThoughtSpot content. The core analytics pattern is: **create a session** → **send a message** → **poll for updates**. The `search_objects` tool is independent of this workflow and can be called at any time. +Analysis, dashboard creation, and model building each follow the same pattern, **start the work** → **poll for updates** until it finishes. +The analysis workflow is **create a session** → **send a message** → **poll for updates**. The `search_objects` and `get_data` tools are independent of these workflows and can be called at any time. * <> + Start an analytical session. @@ -15,9 +17,23 @@ Send a natural language question or follow-up. * <> + Poll for streamed responses. * <> + -Create a dashboard from session answers. +Create a dashboard from session answers or from a description. +* <> + +Change an existing dashboard. +* <> + +Poll a dashboard task that is still running. * <> + Search for existing ThoughtSpot content by name or description. +* <> + +Fetch the columns and rows of a saved Answer or Liveboard. +* <> + +Start a session to build or edit a data model. +* <> + +Send an instruction to the model builder or answer one of its questions. +* <> + +Poll for the model builder's progress. +* <> + +Review and save the model. * <> + List the Orgs your account can access. (OAuth connections on Org-enabled instances only) * <> + @@ -25,6 +41,14 @@ Switch your active Org for the current session. (OAuth connections on Org-enable * <> + Verify that the MCP Server is reachable. +[NOTE] +==== +* The new and updated tools are available only on the MCP server endpoint `?api-version=latest`. Integrations that are pinned to a specific API version do not receive them. +* The server lists `get_data` only for users who have the privilege to download data. +* The server lists the model builder tools only for users who have the data management privilege and the privilege to create or edit data models. +==== + + [#create_analysis_session] == create_analysis_session Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. @@ -32,7 +56,9 @@ Start an analytical session with ThoughtSpot's analytics agent. This is the requ 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. +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. If the instance does not support automatic selection, the tool returns an error that asks for a data source. Find the GUID with xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects], using `types: ["WORKSHEET"]`. If you have only the data source name, you can pass it in the `additional_context` field of `send_session_message` instead. + +The `data_source_id` must be a GUID in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. === Example call @@ -92,7 +118,7 @@ __Optional__|Can be used to provide external information relating to the questio [source,javascript] ---- const sendMessage = await callMCPTool("send_session_message", { - analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. + analytical_session_id: "session-guid-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. @@ -104,10 +130,10 @@ const sendMessage = await callMCPTool("send_session_message", { call_mcp_tool( "send_session_message", { - "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. + "analytical_session_id": "session-guid-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." + "The user's fiscal year starts in April. " "Focus on underperforming regions only." # to influence the analysis. ), }, @@ -131,6 +157,7 @@ call_mcp_tool( * 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. +* Do not send a dashboard request through this tool. To create a dashboard, use xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. ==== [#get_session_updates] @@ -146,7 +173,7 @@ Send the `analytical_session_id` to specify the session to retrieve updates for. [div tabbed-code] -- -[source,typescript] +[source,javascript] ---- const updates = await callMCPTool("get_session_updates", { analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call. @@ -157,7 +184,7 @@ const updates = await callMCPTool("get_session_updates", { ---- call_mcp_tool( "get_session_updates", - {"analytical_session_id": "sess_abc123"}, # Session ID from create_analysis_session. + {"analytical_session_id": "session-guid-abc123"}, # Session ID from create_analysis_session. ) ---- -- @@ -180,9 +207,9 @@ Render these immediately so the user sees progress in real time. |A fragment of Spotter's narration. Concatenate chunks to form the complete narration string. When `is_thinking` is `false`, the chunk is part of the final answer narration, not an intermediate thinking step. -|`answer`|`false` +|`answer`|`true` or `false` |The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable `iframe_url`, and an `answer_id` for creating dashboards. -Exactly one `answer` update is present per question. +The same answer can arrive twice in one response, once with `is_thinking: true` and once with `is_thinking: false`. Both updates carry the same `answer_id`. Render the answer once, and use the `answer_id` to remove duplicates. |==== Poll returning intermediate updates: @@ -223,6 +250,15 @@ Poll returning the final answer: "type": "text_chunk", "text": "Running the query against the sales data model..." }, + { + "is_thinking": true, + "type": "answer", + "answer_id": "{\"session_id\":\"1a3d...\",\"gen_no\":2}", + "answer_title": "Total sales by region", + "answer_data_source_id": "cd252e5c-...", + "answer_query": "[sales] [region]", + "iframe_url": "https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..." + }, { "is_thinking": false, "type": "text_chunk", @@ -255,8 +291,8 @@ A typical response sequence might look like: . Step headings: `step_notification` updates announcing each step Spotter is about to start. . Thinking narration: `text_chunk` updates with `is_thinking: true` describing what Spotter is doing. -. Clarifications or caveats: `text_chunk` updates with `is_thinking: false` explaining assumptions, filters applied, or potential ambiguities in the question. -. The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. +. The answer: an `answer` update containing the visualization title, the underlying query, the `answer_id`, and the embeddable iframe URL. The same answer can arrive again with `is_thinking: false`. +. Final narration: `text_chunk` updates with `is_thinking: false`. This text can explain assumptions, filters applied, or ambiguities in the question, and can include a Markdown summary of the results, such as key takeaways. It can arrive before and after the `answer` update, so the `answer` is not always the last update. This means a complete response might span 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. @@ -265,7 +301,7 @@ Includes three types, `step_notification`, `text_chunk`, `answer`. Flat, fixed k [source,json] ---- -{"is_thinking":true,"type":"step_notification","text":"Searching for Datasets"} +{"is_thinking":true,"type":"step_notification","text":"Searching data models"} {"is_thinking":true,"type":"text_chunk","text":" to find the most relevant dataset..."} {"is_thinking":false,"type":"answer", "answer_id":"{\"session_id\":\"1a3d...\",\"gen_no\":2}", @@ -286,6 +322,8 @@ Each item in the `session_updates` list is a `session_update` object. The `type` |`"step_notification"`|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. |`"text_chunk"` | A streaming fragment of Spotter's narration. Concatenate all chunks to reconstruct the full text. |`"answer"`|Populates `answer_title`, `answer_query`, `answer_data_source_id`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL. +|`is_thinking`|__Boolean__|`true` for intermediate reasoning (`step_notification` updates and thinking `text_chunk` updates). `false` for the final narration and the answer. +|`answer_id`|__String__|Identifier of the answer. Present only when `type` is `"answer"`. Pass it as is to `create_dashboard`. |`text`|__String__|The text content of the message. Present only when `type` is `"step_notification"` or `"text_chunk"`. For `"text_chunk"` updates, concatenate all chunks to form the complete message. |`answer_title`|__String__|A human-readable title describing what the answer shows. Present only when `type` is `"answer"`. |`answer_data_source_id`|__String__|GUID of the data source used to generate the answer. Present only when `type` is `"answer"`. @@ -328,48 +366,70 @@ The full response does not include a preconstructed `iframe_url`. You must build For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. + [#create_dashboard] == 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. +Create a ThoughtSpot dashboard and save it, so that users can revisit or share the results. SpotterViz, the ThoughtSpot dashboard designer, builds the dashboard. Use this tool when a user asks for a dashboard or Liveboard, asks to save analysis results, or wants to recreate a dashboard from another tool. + +You can call the tool in two ways: + +. *From completed analysis*: Pass `answers` collected from `get_session_updates`, with optional `instructions` for layout and style. SpotterViz organizes, styles, and saves the charts. Call this only after `get_session_updates` returns `is_done: true`, because you need the answer ID values from completed answer updates. +. *From a description*: Pass `instructions` that describe the dashboard. Use this when the user asks for a dashboard before any analysis, or wants one recreated from a specification. In this case, do not run the analysis first. SpotterViz replies with `needs_input`, which contains the data source it chose and its plan. Nothing is built until the user confirms the plan. + +Dashboard creation can take a few minutes, so the call can return `in_progress` before the dashboard is ready. === Input parameters +Pass `answers`, `instructions`, or both. [cols="2,4", options="header"] |==== |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 `
` for spacing within the HTML. Include emojis, colors, and a `"Generated on