Mcp server documentation update

modules/ROOT/pages/common/nav.adoc

@@ -8,14 +8,17 @@
 
 * link:{{navprefix}}/whats-new[What's New]
 ** link:{{navprefix}}/whats-new[New features]
+
 *** link:{{navprefix}}/fixed-issues[Fixed issues]
 *** link:{{navprefix}}/known-issues[Known Issues]
 
-** link:{{navprefix}}/embed-sdk-changelog[SDK and API changelog]
+** link:{{navprefix}}/embed-sdk-changelog[SDK changelog]
 *** link:{{navprefix}}/embed-sdk-changelog[Visual Embed changelog]
 *** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog]
+** link:{{navprefix}}/rest-v2-changelog[REST API changelog]
 *** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog]
 *** link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog]
+** link:{{navprefix}}/mcp-server-changelog[MCP Server changelog]
 ** link:{{navprefix}}/deprecated-features[Deprecation announcements]
 
 * Live Playgrounds
@@ -225,14 +228,25 @@ include::generated/typedoc/CustomSideNav.adoc[]
 *** link:{{navprefix}}/webhooks-lb-payload[Webhook response payload]
 *** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts]
 
-* MCP Servers and Tools
-** link:{{navprefix}}/SpotterCode[SpotterCode for IDEs]
-*** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode]
-*** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide]
+* link:{{navprefix}}/SpotterCode[SpotterCode for IDEs]
+** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode]
+** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide]
+
+* MCP Servers and tools
 ** link:{{navprefix}}/ai-analytics-integration[ThoughtSpot AI analytics integration]
-*** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server]
-*** link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to MCP clients]
-*** link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom application or chatbot]
+** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server]
+*** link:{{navprefix}}/mcp-server-spotter3[MCP Server with Spotter 3]
+*** link:{{navprefix}}/mcp-server-legacy[Legacy MCP Server architecture and tools]
+** link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to MCP clients]
+** link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom app]
+** link:{{navprefix}}/mcp-tool-reference[MCP tool reference]
+*** link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (Spotter 3)]
+*** link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (legacy version)]
+** link:{{navprefix}}/mcp-tool-reference[SDK components]
+*** [.typedoc-Function]#link:{{navprefix}}/Function_startAutoMCPFrameRenderer[startAutoMCPFrameRenderer]#
+*** [.typedoc-Interface]#link:{{navprefix}}/Interface_AutoMCPFrameRendererViewConfig[AutoMCPFrameRendererViewConfig]#
+
+
 
 *  link:{{navprefix}}/development-and-deployment[Deployment and integration]
 ** link:{{navprefix}}/development-and-deployment[Development and deployment]

modules/ROOT/pages/mcp-connect-custom-chatbot.adoc

@@ -14,16 +14,11 @@ When integrated, the agent in your custom application can:
 * Support natural language conversation sessions for data questions.
 * Generate embeddable visualizations and programmatically create a Liveboard.
 
-[IMPORTANT]
-====
-Currently, the MCP Server integration does not support link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3 capabilities].
-====
-
 == Before you begin
 Before you begin, review the following prerequisites:
 
 * Node.js version 22 or later is installed and available in your environment.
-* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release version.
+* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later.
 * Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required.
 
 == Authenticating users
@@ -37,8 +32,16 @@ The token generated for the user session is used as a bearer token when your bac
 == Connecting clients
 If your custom chatbot implementation uses Claude, OpenAI, or Gemini LLM APIs to call MCP tools, ensure that your MCP Server endpoint, authentication token, and ThoughtSpot host are included in the API request.
 
+When integrating with apps using custom workflows, ThoughtSpot recommends using the MCP server URL with the date-based `api-version` parameter. This allows you to pin a specific version and avoid introducing unintended changes to custom workflows that rely on tool responses.
+
+* For OAuth clients:
+`https://agent.thoughtspot.app/mcp?api-version={YYYY-MM-DD}`
+
+* For bearer token clients:
+`https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}`
+
 === Claude MCP connector
-If your application uses Claude MCP connector, use the following API request format to connect Claude to the MCP Server:
+If your application uses the Claude MCP connector, use the following API request format to connect Claude to the MCP Server:
 
 [source,bash]
 ----
@@ -57,7 +60,7 @@ curl https://api.anthropic.com/v1/messages \
     "mcp_servers": [
       {
         "type": "url",
-        "url": "https://agent.thoughtspot.app/bearer/mcp",
+        "url": "https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}",
         "name": "thoughtspot",
         "authorization_token": "TS_AUTH_TOKEN@my-instance.thoughtspot.cloud"
       }
@@ -68,10 +71,10 @@ curl https://api.anthropic.com/v1/messages \
 In the above example, the API call includes:
 
 * The user’s message.
-* ThoughtSpot’s MCP Server endpoint `https://agent.thoughtspot.app/bearer/mcp`.
+* ThoughtSpot’s MCP Server endpoint `\https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}`. Replace `YYYY-MM-DD` with an actual date string.
 * An `authorization_token` that encodes which ThoughtSpot instance and user/token to use.
 
-Claude uses the configured MCP Server to call ThoughtSpot MCP tools as needed, using the bearer-style token you provided.
+Claude uses the configured MCP Server to call ThoughtSpot MCP tools as needed, using the bearer token you provided.
 
 === OpenAI Responses API
 If your application uses an OpenAI LLM, use the following API request format to connect OpenAI to the MCP Server:
@@ -87,7 +90,7 @@ curl https://api.openai.com/v1/responses \
       {
         "type": "mcp",
         "server_label": "thoughtspot",
-        "server_url": "https://agent.thoughtspot.app/bearer/mcp",
+        "server_url": "https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}",
         "headers": {
           "Authorization": "Bearer TS_AUTH_TOKEN",
           "x-ts-host": "my-instance.thoughtspot.cloud"
@@ -101,10 +104,10 @@ curl https://api.openai.com/v1/responses \
 In the above example, the API call includes the following parameters:
 
 * MCP as the tool type.
-* ThoughtSpot MCP Server URL.
+* ThoughtSpot MCP Server URL. Replace `YYYY-MM-DD` in the URL with an actual date string.
 * Authentication token and ThoughtSpot host URL.
 
-The OpenAI LLM model uses the configured MCP Server, sends the provided headers on each MCP tool call, and gets the requested data from your ThoughtSpot instance under that token's identity.
+The OpenAI LLM uses the configured MCP Server, sends the provided headers on each MCP tool call, and gets the requested data from your ThoughtSpot instance under that token's identity.
 
 === Gemini API
 
@@ -120,7 +123,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
 const transport = new StreamableHTTPClientTransport(
-  new URL("https://agent.thoughtspot.app/bearer/mcp"),
+  new URL("https://agent.thoughtspot.app/token/mcp?api-version={YYYY-MM-DD}"),
   {
     requestInit: {
       headers: {
@@ -154,7 +157,7 @@ await mcpClient.close();
 
 The above example:
 
-* Creates an MCP client and connects it to the ThoughtSpot MCP Server using `StreamableHTTPClientTransport`.
+* Creates an MCP client and connects it to the ThoughtSpot MCP Server using `StreamableHTTPClientTransport`. Ensure that you replace `YYYY-MM-DD` in the URL with an actual date string.
 * Sends the required headers with the authentication token and ThoughtSpot host URL in MCP requests.
 * Wraps the MCP client as a tool and passes it into `GoogleGenAI` so Gemini can call ThoughtSpot tools as part of answering a user's query.
 
@@ -163,17 +166,20 @@ The above example:
 To verify the integration:
 
 . Start a chat session by asking a question and verify whether your chatbot's LLM is calling the ThoughtSpot MCP tools to generate a response. +
-A typical agentic workflow follows this pattern:
-* Calls `getRelevantQuestions` to break the request into sub-queries
-* Calls `getAnswer` to run those questions in ThoughtSpot and receive structured data and visualization metadata
-* Based on a user prompt, calls `createLiveboard` to save the results in a ThoughtSpot Liveboard.
-. Verify whether the metadata in the output includes `frame_url` to embed a visualization in an iframe or HTML snippet.
+. Verify the tool calls. For information about tool calls and responses, see xref:mcp-tool-reference-guide.adoc[MCP tool reference guide].
+. Verify the Liveboard creation workflow and check whether a Liveboard is created in ThoughtSpot.
+. Verify whether the metadata in the output includes the URL to embed a visualization in an iframe or HTML snippet.
+
+== Displaying visualization in iframe
+Visualizations are returned as ThoughtSpot Answers via iframes. Use the xref:startAutoMCPFrameRenderer.adoc[startAutoMCPFrameRenderer] function to display the iframe.
+
+An example project showing how this is used in the `app.jsx` file with a code sample is available in the link:https://github.com/thoughtspot/developer-examples/blob/main/mcp/python-react-agent-simple-ui/client/src/App.jsx[developer-examples GitHub repository, window=_blank].
 
 == Troubleshooting errors
 
 Cannot connect to MCP Server::
 
-* Verify if the MCP Server is reachable.
+* Verify that the MCP Server is reachable.
 * Ensure that the correct MCP Server URL is used in API requests.
 * If the issue persists, verify the logs and contact ThoughtSpot Support for assistance.
 
@@ -183,173 +189,13 @@ Authentication failure::
 * Verify whether the MCP Server and ThoughtSpot host are reachable.
 * Verify whether the user has the necessary privileges to view data or create content.
 
-== MCP tool calls and response output
-The following sections outline the MCP request input schema and data structure of the response.
-
-=== ping
-Runs a basic health check to validate that the MCP Server is reachable.
-
-[source,ts]
-----
-const tsPing = await callMCPTool("ping", {});
-----
-
-=== getDataSourceSuggestions
-Suggests appropriate ThoughtSpot data models for a given natural language question.
-
-
-==== Example request
-
-[source,ts]
-----
-const dsSuggestions = await callMCPTool("getDataSourceSuggestions", {
-  query: "show me sales by region" // user's query
-});
-----
-
-==== Response format
-
-Returns an object containing an array of suggestions:
-
-[source,json]
-----
-{
-  "suggestions": [
-    {
-      "header": {
-        "guid": "worksheet-guid-123",
-        "displayName": "Sales Analytics",
-        "description": "Sales performance by region, product, and channel"
-      },
-      "confidence": 0.92,
-      "llmReasoning": "This worksheet contains sales metrics and regional dimensions relevant to the query."
-    }
-  ]
-}
-----
-
-Key fields are:
-
-* `header.guid`: Unique ID for the datasource. The `datasourceId` is used in `getRelevantQuestions` and `getAnswer` calls.
-* `header.displayName`: Name of the data source.
-* `header.description`: Optional description of the data source.
-* `confidence`: Numeric score indicating the confidence of the system about a data model being the right match for the user’s query.
-* `llmReasoning`: LLM's reasoning for the suggestion.
-
-=== getRelevantQuestions
-Uses ThoughtSpot’s reasoning engine to generate AI-suggested sub-queries that help generate specific answers for a given data context.
-
-==== Example call
-
-[source,ts]
-----
-const result = await callMCPTool("getRelevantQuestions", {
-  query: "show me sales data", // User's natural language query
-  datasourceIds: ["model-guid-123"], // Array of worksheet/datasource GUIDs
-  additionalContext: "User is interested in the data for underperforming regions and products"
-});
-----
-
-==== Response example
-
-[source,json]
-----
-{
-  "questions": [
-    "What is the total sales revenue by region?",
-    "Which products have the highest revenue?",
-    "What are the top selling categories?"
-  ]
-}
-----
-
-Each returned question can then be passed individually into `getAnswer`.
-
-=== getAnswer
-Executes a natural language question for a given data context and returns the resulting data and visualization metadata. Clients can use this data and frame URL to render visualizations.
-
-==== Example call
-
-[source,ts]
-----
-const result = await callMCPTool("getAnswer", {
-  question: "Total sales by region", // Natural language question
-  datasourceId: "model-guid-123" // Worksheet/datasource GUID
-});
-----
-
-==== Response example
-
-[source,json]
-----
-{
-  "question": "Total sales by region",
-  "session_identifier": "abc-123-def-456",
-  "generation_number": 2,
-  "data": "\"Region\",\"Total Sales\"\n\"East\",100000\n...",
-  "frame_url": "https://...",
-  "fields_info": "..."
-}
-----
-
-Key fields are:
-
-* `session_identifier`: Unique session ID used to group answers. Required when creating a Liveboard from this answer using the `createLiveboard` MCP tool.
-* `generation_number`: Version number for this answer. Required for Liveboard creation.
-* `question`: The executed question; useful for display and to pass it into the `createLiveboard` request.
-* `data`: Data returned in encoded format. Contains column headers and all returned rows in comma-separated format, which can be parsed to render tables or charts in your application.
-* `frame_url`: Optional iframe URL for embedding the visualization in your UI.
-* `fields_info`: Descriptive metadata about the fields and chart, useful for explanations.
-
-=== createLiveboard
-
-Creates a ThoughtSpot Liveboard with one or more answers from the results. This is a two-step process and includes the following calls:
-
-. Call `getAnswer` to generate visualizations and obtain `session_identifier` and `generation_number`.
-. Call `createLiveboard` with those values to create the Liveboard.
-
-==== Example call
-
-[source,ts]
-----
-const answerData = JSON.parse(answerResult.result.content);
-
-const liveboardResult = await callMCPTool("createLiveboard", {
-  name: "My Sales Dashboard",
-  noteTile: "My Sales Dashboard was created by TS MCP Chat", // Description text for the Liveboard
-  answers: [{
-    question: answerData.question, // Display name for the Liveboard
-    session_identifier: answerData.session_identifier,
-    generation_number: answerData.generation_number
-  }]
-});
-----
-
-Required attributes are:
-
-* `noteTile`: Use this field for any Liveboard description or notes; a separate description field is not supported.
-* `answers`: Required array. Each item must include `question`, `session_identifier`, and `generation_number` from a prior `getAnswer` call.
-
-==== Response example
-
-[source,json]
-----
-{
-  "liveboardId": "liveboard-guid-here",
-  "name": "My Sales Dashboard",
-  "frame_url": "https://..."
-}
-----
-
-Key fields are:
+== MCP tools and response
+For information about tool calls and responses, refer to the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide].
 
-* `liveboardId`: GUID of the created Liveboard.
-* `name`: Name of the Liveboard.
-* `frame_url`: URL that can be embedded to display the Liveboard.
 
 == Additional resources
 
 * To view the MCP Server code, go to the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank].
-* For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI].
+* For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI, window=_blank].