Other semantic layers expose one endpoint: render SQL for a metric. Semantic Rails exposes the loop an agent walks around that SQL — thirteen MCP tools with inline scope classification, structured errors when something doesn't fit, explainable plans when it does. DuckDB locally, Snowflake through the connector.
An agent that "just writes SQL" guesses object IDs, hallucinates join paths,
and hands you a query it can't explain. Semantic Rails replaces the guess
with thirteen inspectable MCP tools — capabilities for
orientation through execute for warehouse results, plus
plan, valid-values, and three segment-* tools.
Scope classification runs inline on discover and
plan — out-of-scope intents come back as structured
blocks before the planner touches the warehouse.
plan, catalog, valid-values, and
segment helpers are also exposed for agents that need them.
SQL-generation layers expose one surface — render SQL for a metric. An agent runtime exposes the steps an agent takes before it commits to SQL, so failures land as recoverable structured errors, not silently-wrong rows.
capabilities, discover, inspect,
plan, build-options, validate,
compile, and execute are each their own MCP
tool — alongside catalog, valid-values,
and three segment helpers. Agents can stop, branch, or backtrack at
any step instead of being forced through one opaque "give me SQL" call.
When a query doesn't fit, the runtime returns a typed envelope with
recovery_hints and closest_matches — usable
directly by the next tool call, no prompt-engineering glue required.
Every discover and plan call runs the
scope classifier inline. Intents that share no content tokens with the
package come back as out_of_scope or
low_relevance blocks — off-topic questions don't quietly
hit the warehouse.
Mixed-grain requests, metric predicates, temporal-validity joins, and same-store conversion live in the planner — not as helper views every team has to re-author.
compile's response carries the full explain payload —
alias resolution, chosen join paths, rewrite strategy, logical plan,
SQL AST, and rendered warehouse SQL — flattened into
compile_response_metadata so reviewers see everything
before trusting the result.
Authored as versioned YAML with graphs, joins, clocks, value domains,
examples, and package-local tests. The CLI ships
parse-config, validate-config, and
test-package.
MetricFlow, Cube, Malloy, and Snowflake Semantic Views are governed SQL-generation layers. They render SQL for a metric. Semantic Rails renders the whole loop an agent walks around that SQL.
| Capability | MetricFlow | Cube | Malloy | Snowflake SV | Semantic Rails |
|---|---|---|---|---|---|
| MCP server (stdio + HTTP) | |||||
capabilities → catalog → discover → inspect → plan/build-options → validate → compile → execute plus 4 more (valid-values, segment-validate, segment-explain, segment-preview) — 13 MCP tools total |
|||||
Structured error envelope (recovery_hints, closest_matches) |
|||||
| Classifier + relevance-floor gate before planning | |||||
| MIT-licensed | Apache 2.0 | Apache 2.0 | proprietary | ||
| Compile without execute | limited | ||||
| Explain plan as structured JSON | partial | partial | partial | ||
| Local DuckDB execution |
Clone, install with uv, validate the Jaffle reference package,
and start the MCP server. The whole loop runs locally against DuckDB —
no warehouse credentials required for the first pass.
uv sync --group dev.validate-config.semantic-layer mcp stdio and connect from your agent.uv sync --group dev uv run semantic-layer validate-config --package jaffle_shop uv run semantic-layer serve --package jaffle_shop --port 8081 uv run semantic-layer mcp stdio --package jaffle_shop # optional: Snowflake via Snow CLI snow connection list uv run semantic-layer validate-config --package tpch_sf1_showcase uv run semantic-layer serve --package tpch_sf1_showcase --port 8092
Read the source. Run the quickstart. If it doesn't fit the way your agent thinks, tell us why — the design is meant to be inspected and argued with.