> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/kaiya/tellius-mcp-server.md). # 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:///mcp ``` The 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: ```bash claude mcp add --transport http tellius https:///mcp ``` 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. {% hint style="warning" %} **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. {% endhint %} #### **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. | Parameter | What to send | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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_views` to 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_details` for its full column schema, data types, and sample values. * Clients that support MCP resources can read the same information directly from `tellius://business-views` and `tellius://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. | Control | Selected value | Phrase to include | | ------- | -------------------- | --------------------------- | | Metric | Revenue | `Revenue` | | Product | All products | omit | | Product | *a specific product* | `for ` | | Region | National | omit | | Region | *a specific region* | `in the region` | | Period | *a quarter* | `for ` | | Period | *a date range* | `for through ` | Assembled, a question follows this shape: ``` [for ] [in the region] [for ] ``` {% hint style="success" %} 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. {% endhint %} #### **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: ```json { "summary": "Revenue in the region for was ...", "data": { "columns": ["Region", "Quarter", "Revenue"], "rows": [["", "", 0.0]] }, "sql": "SELECT SUM(Revenue) ... WHERE ..." } ``` 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`. {% hint style="warning" %} 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`. {% endhint %} ### **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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.tellius.com/kaiya/tellius-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.