Tellius MCP server
Tellius exposes its analytics engine through an MCP (Model Context Protocol) server. Any MCP-compatible client (Claude Desktop, Claude Code, or an application you build yourself) can connect to it and work with your Business Views, ask questions in plain English, run agentic Missions, and set up scheduled delivery.
The MCP server holds no data of its own. It passes your requests to Kaiya, which interprets the question, generates the SQL, runs the analysis, and returns the result. Metric definitions, joins, hierarchies, and row-level security stay inside your Business Views, so an answer retrieved through MCP follows the same governed logic as the same question asked inside Tellius.
What you can build with it
Connect your own AI client: Point Claude Code, Claude Desktop, Cursor, or any other MCP client at Tellius and ask questions about your governed data from the tool you already work in.
Retrieve metrics into your own application: Your app owns the interface (KPI cards, filters, dropdowns) and calls Tellius for the numbers. Users never sign in to Tellius directly.
Add contextual follow-ups: A user looking at a metric asks why it moved. Your app sends the question with the same filters that produced the metric, so the answer describes the slice on screen.
Automate recurring analysis: Run a saved Mission on a schedule and deliver the output by email, Slack, or Teams.
How to connect an MCP client
No need to install or run anything locally. The Tellius MCP server is hosted on your Tellius deployment. You configure an MCP client to point at its URL, sign in once, and the tools appear.
Ask your Tellius administrator for your MCP endpoint URL. The host varies by deployment and ends in /mcp:
https://<your-mcp-host>/mcpThe server speaks standard MCP over streamable HTTP, so any MCP-compatible client can connect. No custom protocol, plugin, or Tellius SDK is required. A server-sent events transport is also available for older clients that need it, though HTTP is preferred where a client supports both.
Two ways to sign in
Browser sign-in: Available to all users. Configure the MCP URL in a client that supports OAuth. The first time you connect, your browser opens a Tellius confirmation page. Approve it, and the client stores its credentials and connects without asking again.
Client ID and secret: For clients that run without a browser. An administrator creates MCP OAuth credentials in Tellius under Admin Settings, and those go into the client's configuration. Only administrators can create these credentials.
Use browser sign-in wherever the client supports it. It needs no administrator involvement, and each user's own permissions apply.
Claude Code
Add the server from a terminal, then authenticate inside a session:
Add --scope user to make it available across all your projects rather than only the current one. Then start Claude Code and run /mcp to complete the browser sign-in and check the connection status. claude mcp list shows whether the server is registered.
Claude Desktop and other clients with a connector UI
Open the client's settings, find the section for adding a custom connector or MCP server, and paste the URL. The client opens a browser window for sign-in the first time you use it.
Headless clients
Clients that cannot open a browser, such as Cursor, use the client ID and secret instead. Ask an administrator to create MCP OAuth credentials in Admin Settings, then enter them in the client's configuration alongside the MCP URL.
Confirming it worked
List the available tools in your client.
A working connection shows the Tellius tools, including
tellius_ask.If the tool list is empty or the server shows as disconnected, the sign-in has probably not completed. Trigger it again from the client.
Certificate errors. If your client reports a TLS error when connecting, the host may be serving an incomplete certificate chain. Add the missing intermediate CA to your client's trust store or CA bundle. This is a host configuration issue rather than a problem with your client.
Permissions
Every request runs as a specific Tellius user. Business View permissions and row-level security are applied to that user, so an answer retrieved through MCP reflects the same access the user has inside the product.
How to start asking a question: tellius_ask
tellius_ask is the tool behind most integrations. It takes a question in plain English plus the Business View to answer it from, and returns the answer along with the data and the query that produced it.
question
The request in plain English, with filters written into the sentence.
business_view_ids
A list containing the Business View id.
include_raw
Set to true to receive the data table and the generated SQL alongside the written answer. Required if you plan to read an exact value or validate the result.
Always send the business_view_id rather than the Business View name. Names can be edited; ids are stable.
Finding the Business View id
Use
tellius_list_business_viewsto search and page through the Business Views you have access to.Each result carries its
business_view_id.To check that a Business View holds the metric and dimensions you need, call
tellius_get_business_view_detailsfor its full column schema, data types, and sample values.Clients that support MCP resources can read the same information directly from
tellius://business-viewsandtellius://business-views/{id}/schema.
Writing filters into the question
Filters are not passed as separate structured fields. They go into the question text, and only the Business View id travels separately.
Each filter you selected becomes a short phrase in the question.
Filters set to "All" are simply left out. You do not need to write "for all products". Asking without naming a product already covers all of them.
Metric
Revenue
Revenue
Product
All products
omit
Product
a specific product
for <product>
Region
National
omit
Region
a specific region
in the <region> region
Period
a quarter
for <quarter>
Period
a date range
for <start> through <end>
Assembled, a question follows this shape:
Keep the wording identical for a given card. Use the same phrasing every time for the same metric, changing only the filter values. Consistent wording produces consistent SQL, which is what keeps a displayed number stable between refreshes.
Reading the response
With include_raw set to true, the response carries three parts:
A written summary: A sentence answering the question, suited to a chat or drill-down view.
A data table: Columns and rows holding the actual values.
The SQL: The query Tellius generated and ran.
The response is shaped roughly like this:
Read the exact field names from the tellius_ask output schema shown in your MCP client. A chart definition may also be returned.
Validating before you display
Check the response before rendering it as a number.
1. Confirm you received data, not a follow-up. The response may come back asking a clarifying question, or asking the user to sign in. Treat either as "no value yet" rather than rendering it.
2. Check the SQL against your intent. The returned SQL shows the filters and the aggregation that were used. Confirm they match what your interface asked for. This is the strongest guard against a misread question, and it is the reason to send include_raw: true even when you only need a single number.
3. Sanity-check the value. Confirm it is numeric and within a plausible range. Where your data has a natural hierarchy, a rollup check works well: the parts should sum to the whole for the same metric and period.
Questions appear in Tellius
Each question asked through tellius_ask is saved as a conversation turn in Tellius. The exchange is visible in the Kaiya interface even when the user never opens Tellius directly, which keeps external activity auditable alongside in-product usage.
Investigating "why": tellius_deep_insight
tellius_deep_insight runs a multi-step agentic investigation rather than a single query. Use it for questions about causes and drivers, where a single aggregation would not answer the question.
It takes the same shape of request as tellius_ask and returns the same shape of response. A deep insight plans, runs several steps, and validates its own findings, so a call can run for a few minutes on a large Business View.
Set a generous client timeout. A timeout tuned for a simple query will cut off a deep insight before it finishes.
Avoid firing many deep insights at once. Long-running calls hold resources for their whole duration. Queue them rather than launching a large batch in parallel, or fast queries issued at the same time may be left waiting.
Running Kaiya Missions and workflows
Saved Missions and workflows can be executed headlessly through tellius_run_workflow, passing the workflow id and any inputs it needs.
A Mission can pause for input at two different points, and the tool you call to continue depends on which one paused it.
A question asked before the run starts comes from the Mission's own defined inputs. Answer it by calling tellius_run_workflow again with the input filled in.
A question asked while the Mission is already running comes from a step that requests input mid-execution. This kind of pause carries a conversation_id. When you see one, call tellius_resume_workflow with that same conversation_id.
Calling tellius_run_workflow again to answer a mid-run question starts a brand-new run instead of continuing the paused one, so the same question comes back and the Mission never completes. The presence of a conversation_id in the clarification is the signal to switch to tellius_resume_workflow.
Scheduling delivery
tellius_create_schedule sets up recurring delivery of either a saved workflow or a stored ad-hoc question. You supply the name, the cadence, what to run, and where to send it.
Creating the schedule records it. Tellius runs it on its cadence from then on and delivers the result to the channels you configured, through email, Slack, or Teams. To send to Slack or Teams, look up the channel ids first with tellius_list_slack_channels or tellius_list_teams_channels.
Schedules listed through tellius_list_schedules are scoped to the calling user.
How your data is handled
Where the MCP server runs. The Tellius MCP server runs inside your Tellius deployment. The server holds no data of its own. It provides an MCP interface over existing Tellius capabilities and forwards each request to Kaiya, which does the work.
When a language model is involved. The MCP server itself does not use a language model. Whether one is involved depends on the request. A question sent through tellius_ask uses a model to interpret it and generate the query. A request like tellius_list_business_views does not — it returns the list directly.
Your administrator configures which model Kaiya uses under Settings → Application Settings.
What the model receives. Business View schema is sent so the model can write the query, and query results are sent so it can summarize them or build a report. Underlying row-level data does not leave your environment.
Conversation history. Questions asked through MCP are saved as conversation turns in Tellius and remain available in the Kaiya interface.
Last updated
Was this helpful?