How the MCP server works¶
This page explains how the AI Analyst MCP server works: how an app connects and signs in, what the server checks on every call, and what each tool takes and returns. It is for technical readers who want to understand or evaluate the integration. To connect an app, see Connected apps (MCP).
Two models, two jobs¶
Two AI systems are involved when you ask a question from an external app, and they do different work.
| The app's model | The AI Analyst | |
|---|---|---|
| Runs in | Claude, ChatGPT, Cursor or another app | AI Analyst |
| Decides | Which tools to call, and how to word the final reply | How to answer the question from your data |
| Sees | Your chat, plus whatever the tools return | Your semantic layer and the data it queries |
The app's model never writes SQL and never connects to your data sources. It hands the question to an AI Analyst, which works the way it does in Explorer: it uses the models, metrics and glossary in your semantic layer, runs the queries, and returns an answer with any charts and tables it produced.
A typical question goes through these steps:
- You ask the app a question, for example What was revenue last quarter?
- The app's model calls
list_analystsand gets the AI Analysts you can ask. - It calls
ask_analystwith your question. The MCP server starts a conversation with that AI Analyst, as you. - The AI Analyst answers from your data. The MCP server returns the answer, references to any charts and tables, and links.
- The app's model calls
show_artifactfor the charts and tables worth showing, and the app draws them in the chat. - The app's model writes its reply to you.
Connection¶
- Transport: a remote MCP server over Streamable HTTP, at one address:
https://<your AI Analyst host>/mcp. The server acceptsPOSTonly. - No sessions: each request is handled on its own. The server keeps no MCP session between requests, so there is nothing to resume or expire on the protocol level.
- Local servers: there is no local (stdio) server to install.
Sign-in¶
The MCP server uses OAuth, so the app never handles your AI Analyst password.
- The app calls the server without a token and is told where to sign in. The sign-in service is at
https://<your AI Analyst host>/mcp/oauth, and both are described by the standard OAuth discovery documents. - The app opens your browser on AI Analyst. You sign in as usual, including through Enterprise SSO.
- A consent page names the app and the organization. Every sign-in stops at this page, even if you approved the same app a moment ago.
- When you click Allow, the app receives an access token and a refresh token for this server.
What to know about the tokens and clients:
- Only listed apps can sign in. Each supported app is identified by its published client identity, and its redirect addresses are fixed. There is no open or dynamic client registration.
- PKCE is required for every sign-in.
- Access tokens last one hour and are opaque. The app refreshes them automatically. Each refresh token works once; reusing a spent one ends the connection.
- A connection lasts 30 days from the moment you allow the app. After that, the app sends you through sign-in again.
- A connection is bound to one member, one app and one organization. To use another organization, connect again and choose it on the consent page.
What happens on every call¶
The server repeats these checks on every tool call, so a change in Settings takes effect on the next request.
- Who is calling. The token is resolved to the member, the organization and the app.
- Is it still allowed. The MCP server must be on for the organization and the app must be allowed. If not, the server answers
401and the app offers to reconnect. - Is the organization active. If the trial has ended, access is on hold, or the organization is pending deletion, the tool returns an error that names the reason and does no work.
- Does the member still have access. The member must hold the Chat capability in at least one Workspace. If they hold none, the connection ends.
- Run as the member, with chat access only. The call runs with the member's identity and the Chat capability, never with Edit, even when the member holds it. That is why only deployed AI Analysts that the member can use in Explorer are reachable.
An AI Analyst, conversation or Artifact the member can't open is reported as not found. The server does not reveal that it exists.
What a tool returns¶
Every tool result has two parts:
- Text that the app's model reads.
- Structured content, a JSON object with the same information in a fixed shape, for apps that use it.
Results that name a conversation or an Artifact include a url that opens it in Explorer, in the right organization and Workspace.
Six of the seven tools only read. They are marked read-only for the app, so most apps call them without asking. ask_analyst starts work in AI Analyst and is not marked read-only, so some apps ask you to confirm it.
Tool reference¶
list_analysts¶
Lists the AI Analysts the member can ask.
- Input: none.
- Returns: for each AI Analyst, its id, name, description, Workspace, and up to three suggested questions.
- Scope: deployed AI Analysts in every Workspace where the member can chat, limited to the ones whose audience includes the member.
ask_analyst¶
Asks an AI Analyst a question, or follows up in an existing conversation.
- Input:
question, plus exactly one ofanalyst_id(start a new conversation) orconversation_id(follow up). - Returns:
status, theanswer, the AI Analyst, theconversation_id, a link to the conversation, and a list of the charts, tables and reports the AI Analyst presented (id, kind, title, link). The list does not include their data. - Waiting: the tool waits up to four minutes for the answer. While it waits, an app that asked for progress gets an update for each step the AI Analyst takes.
- Slow answers: if the answer isn't ready in time,
statusisrunningand the result tells the app to callget_answer. The AI Analyst keeps working. - One question at a time: a follow-up sent while the previous question is still running is refused, and the running question is left alone.
- Counts as a message: each question counts against the organization's message allowance. Over the limit, the answer is the message-limit notice.
A conversation started this way is a normal conversation. It is recorded with the source MCP and the app's name, and it appears in the member's Explorer history.
get_answer¶
Reads the answer of a conversation whose last question was still running.
- Input:
conversation_id. - Returns: the same shape as
ask_analyst. - Waiting: waits up to one minute. If the AI Analyst is still working, the result says to call
get_answeragain.
search_conversations¶
Lists or searches the member's conversations, so a follow-up can continue the right one.
- Input: optional
query, optionalanalyst_id,limit(1 to 50, default 20) andcursor. - Matches: the conversation title and the text of the questions asked, ignoring case. Without a query, it lists conversations newest first.
- Returns: for each conversation, its
conversation_id, title, AI Analyst, Workspace, last update, a short snippet of the question, and whether the AI Analyst is still working on it.next_cursoris set when there are more. - Scope: conversations the member owns that were started in Explorer or from an external app. It leaves out Slack and Microsoft Teams threads, Studio test runs, deleted conversations and read-only conversations.
- Not included: answers, charts and reports. To read those, the app continues the conversation or reads an Artifact.
search_artifacts¶
Lists or searches the member's saved Artifacts.
- Input: optional
query, optionalkind(chart,tableorreport),limit(1 to 50, default 20) andcursor. - Matches: Artifact titles, ignoring case. It does not search inside the data. Without a query, it lists Artifacts newest first.
- Returns: for each Artifact, its id, kind, title, Workspace, whether the member owns it, when it was created, and its link.
next_cursoris set when there are more. - Scope: saved Artifacts the member owns or that are shared with them. Archived Artifacts and unsaved ones are left out. An unsaved Artifact is reached through the conversation that produced it.
read_artifact¶
Returns one Artifact as text, so the app's model can judge whether it is relevant or answer a question about it. It draws nothing.
- Input:
artifact_id, fromsearch_artifactsor from an answer. - Chart or table: the title, the columns, the full row count, and a preview of the first 50 rows. For a chart, the text also says what the chart plots.
- Report: the report's text in reading order. Each embedded chart or table appears in place as its title and a preview of its first 10 rows. The result ends with the report's link and tells the app to give you that link, so you read the report itself in AI Analyst.
- Stored data only: the tool returns the Artifact as it was saved. It does not run a query or start a conversation.
show_artifact¶
Displays charts and tables to the member in the chat.
- Input:
artifact_ids, between one and eight references. They come back in the order given. - Chart or table: the title, columns, rows, a text preview and the link. A chart also carries its chart specification and your organization's chart theme.
- Report: returned as a link, never drawn.
- Limits: up to 200 rows per Artifact, and the whole result is kept under about 100,000 characters. An Artifact that was cut is marked as truncated, with the full row count stated.
- Stored data only: like
read_artifact, it does not run a query. - Partial results: a reference the member can't open is skipped, and the others still come back.
The in-chat view¶
show_artifact is the only tool that declares an in-chat view. The view uses MCP Apps, an extension of MCP for interactive content, and whether it is drawn is up to the app.
- Where the app supports it, the view draws each chart and table with your organization's chart theme. You can switch a chart between Chart and Data, and open each item with Open in AI Analyst. A report appears as a card with an Open report link.
- Full screen is offered only in apps that provide it.
- The view makes no network requests of its own. It draws only what the tool returned.
- Where the app doesn't draw the view, the text preview and the link in the same result stand on their own.
Audit and monitoring¶
- Turning the server or an app on or off, allowing an app, and the end of a connection are recorded in the audit log. So are questions asked (
turn.start, with the MCP source and the app) and Artifacts read or shown (artifact.access). - Conversations from external apps can be reviewed in Studio Monitoring by filtering on the MCP channel.
See MCP server settings for the full list of audit actions.