MCP Tools Reference

All tools are available through the project MCP endpoint at POST /mcp/<project-slug>/mcp. Tools operate within the scope of the project identified by the URL slug.

Semantic models are stored internally as OSI YAML, but all tools that return model information (get_semantic_model, get_datasets) serve a compressed markdown digest instead of raw YAML. This digest uses 3–5× fewer tokens while preserving field types, descriptions, enums, examples, relationships, and instructions.

list_semantic_models

List semantic models the authenticated token has access to.

Parameters: None

Returns: A list of model names and descriptions, filtered by the token’s scopes. Reads from published (assembled) YAML files.

get_semantic_model

Get an overview of a semantic model with datasets, relationships, and metrics. Supports scoped pagination to drill into a specific section independently.

Parameters:

Parameter	Type	Required	Description
`modelName`	string	Yes	The semantic model name (filename without `.yaml`)
`scope`	`"datasets"` \| `"relationships"` \| `"metrics"`	No	Section to retrieve independently. Omit for full overview (first page of each section).
`page`	number	No	Page number within the scope (default 1, items per page configured per project). Only meaningful with `scope`.

Returns: Compressed markdown digest (not raw YAML). Each dataset row includes its table name (the quoted dataset name, e.g. "orders") for use in queries. Agents write bare dataset names in SQL — the correct schema is resolved automatically via DuckDB’s search_path.

get_datasets

Get one or more datasets with all their fields as compact markdown lists with types, examples, enums, synonyms, and instructions. Pass up to 10 datasets in a single call to reduce round-trips. Each dataset entry specifies its own page for independent field pagination.

Parameters:

Parameter	Type	Required	Description
`modelName`	string	Yes	The semantic model name (filename without `.yaml`)
`datasets`	`{ name: string, page?: number }[]`	Yes	Datasets to retrieve (1–10), each with an optional `page` (default 1)

Returns: Compressed markdown digest with compact field lists including data types, expressions, dimension info, enums, examples, and AI context.

execute_query

Run a read-only SQL query scoped to a semantic model’s VIEWs.

Parameters:

Parameter	Type	Required	Description
`modelName`	string	Yes	The semantic model to query against
`sql`	string	Yes	DuckDB SQL using bare dataset names (e.g. `FROM "orders"`), with `$1`, `$2`, … placeholders
`params`	string[]	No	Parameter values for positional placeholders (defaults to `[]`)
`store`	boolean	No	When `true` (default), the query is stored and a `storedQueryId` is included in the response for later re-execution via `execute_stored_query`

Returns: JSON with columns, rows, and optionally storedQueryId (when store is true). Results capped at 1,000 rows (includes truncated: true flag when exceeded). 30-second timeout.

Validation Rules

Only SELECT, WITH, EXPLAIN, and DESCRIBE statements allowed
Multi-statement queries rejected
Raw catalog references (e.g., shopify.public.orders) rejected — use bare dataset names instead
Explicit _scope_ prefixes rejected — dataset names resolve automatically via search_path
SET statements blocked

Security Hardening

Each query runs in a DuckDB connection with:

enable_external_access = false: no file reads, network access, or COPY operations
threads = 2, memory_limit = '512MB': resource limits
search_path set to the model’s scoped schema so bare dataset names resolve to the correct VIEWs

execute_stored_query

Re-execute a previously stored query by its ID. The storedQueryId is returned by execute_query when store is true (the default). Optionally override the original parameter values.

Parameters:

Parameter	Type	Required	Description
`storedQueryId`	string	Yes	The stored query ID returned by a previous `execute_query` call
`params`	string[]	No	Override parameter values; if omitted, the original stored params are used

Returns: JSON with columns and rows in the same format as execute_query. Same result limits (1,000 rows) and timeout (30s) apply.

request_improvement

Submit an improvement request for a semantic model. Use this when you or a user discover issues like missing fields, incorrect descriptions, wrong relationships, or any other quality problem with a semantic model.

Parameters:

Parameter	Type	Required	Description
`modelName`	string	Yes	The semantic model this improvement applies to
`title`	string	Yes	Short summary of the improvement (max 200 chars)
`description`	string	Yes	Detailed description of the issue or requested change (max 2,000 chars)

Returns: Confirmation that the improvement request was submitted.