Skip to main content

C2026.7 Tools Reference

This section provides information on working with the C2026.7 MCP Server, as well as detailed descriptions of the tools it includes.

Tools overview​

When working with the MCP Server tools, be aware of the following.

Intended workflow​

The MCP Server tools are intended to be used in the pipeline listed below. The results from each step in this workflow inform the steps after it.

  1. list_models finds the available models and their column groups.
  2. explore_columns finds candidate columns for querying.
  3. focus_columns confirms every column that a query references.
  4. run_query runs the query.
  5. get_outbound_queries audits the query that hit the data warehouse.

SQL query restrictions and recommendations​

Queries issued by the MCP Server tools have some restrictions:

  • They can be SELECT only.
  • They cannot contain CTEs. The WITH keyword is rejected. Self-joins and subqueries are also rejected.
  • Only one model is permitted per query. You cannot perform cross-model joins.

Queries that do not meet these criteria are rejected by the server with a validation error.

Additionally, AtScale recommends writing your SQL to avoid the following:

  • Using NULLIF. This should be rewritten as CASE WHEN.
  • Wrapping metrics in SUM() or AVG(). Aggregation is defined in the model.
  • Using metrics in GROUP BY or ORDER BY clauses.

These are not rejected by the server, but will fail later.

Agent confirmation​

All of the MCP Server tools carry readOnlyHint: true, and the server independently rejects non-SELECT statements. This removes per-call confirmation prompts in clients like Google Gemini Enterprise.

Agent guardrails​

The tool descriptions embed a mandatory pre-query protocol: load the query skill, confirm ambiguous column choices with the user, never fabricate numbers, answer only from the semantic layer. Because of this, the agent may exhibit behavior like pausing to confirm column choices.

Server version​

The MCP Server version is reported in the MCP initialize handshake, rather than by a specific tool.

Note

The reported version is the version of the MCP Server itself, not AtScale. The MCP Server version will be 0.1.0 or similar, not C2026.7.0.

Tools list​

AtScale C2026.7 provides the following MCP Server tools.

Note

The Required parameters listed below are functionally required, meaning they are required for the call to actually succeed.

list_models​

  • Required parameters: None
  • Optional parameters: force_refresh

Lists available models with names, schemas, descriptions, and the column_groups mapping (dimension groups > fact datasets) used to validate that a query's columns are compatible.

explore_columns​

  • Required parameters: catalog, schema, table, plus one filter
  • Optional parameters: search_terms, folder, role, column_group, force_refresh

Returns the names and descriptions of a model's columns, grouped by column group. You can filter by search_terms (case-insensitive substrings over names and descriptions, model-wide), or scope structurally by folder, role (dimension, measure, calculation_group), or column_group. One filter is required; note that search terms and structural scopes are mutually exclusive.

focus_columns​

  • Required parameters: catalog, schema, table, columns
  • Optional parameters: force_refresh

Returns the full per-column metadata (CSV) for an exact set of names from a prior explore_columns run. Results include the column's data type, role, aggregation, description, column group, hierarchy, required dimension, calculation MDX, semi-additive flag, calculated members, and sampled_values (a preview of stored dimension values for confirming filter literals; for example, 2008 vs CY2008) without a preview query. Unknown names are rejected. This is required for every column a query will reference.

run_query​

  • Required parameters: query
  • Optional parameters: None

Validates and executes a SQL SELECT in one step. The query is first validated: an invalid column path (missing required dimension, non-conforming metric/dimension pair) returns a validation error without executing (so no data warehouse cost). Valid queries return JSON rows, non-fatal warnings, and a queryId for outbound-SQL lookup. SELECT-only; non-SELECT statements are rejected.

get_outbound_queries​

  • Required parameters: queryId
  • Optional parameters: None

Returns the outbound data warehouse SQL AtScale dispatched for a previously executed query, as a JSON array of {outboundQueryId, sql}. Takes the queryId returned by a prior run_query.

Note

Access to outbound query details requires the queries_view role. For more information, see Identity Broker Default Roles.

get_sml_skills​

  • Required parameters: None
  • Optional parameters: skill_name

Fetches semantic-layer skills (protocols and guidance) with progressive disclosure:

  • No argument lists all skills.
  • skill_name returns a skill body.
  • skill:section returns one section or reference file.

The query-semantic-layer skill is the canonical query protocol and should be loaded before querying.