version:0.1 doc:agent-quickstart updated:2026

Agent Quickstart

Use this path when an LLM agent, MCP client, or internal app needs to query governed metrics without jumping straight to SQL. Semantic Rails is designed around staged inspection: discover the surface, validate a draft, compile SQL, then execute only when the request is supported.

1. Choose a transport

Surface	Use it for	Start command or URL
Hosted MCP demo	Public evaluation against synthetic Jaffle Shop data	`https://semantic-rails.com/mcp`
Local MCP stdio	Desktop agents and local MCP clients	`uv run semantic-rails mcp stdio --package jaffle_shop`
Local MCP HTTP	HTTP-capable MCP clients during development	`uv run semantic-rails mcp http --package jaffle_shop --host 127.0.0.1 --port 8091`
Local HTTP API	Apps that call stable `/api/v1/*` routes directly	`uv run semantic-rails serve --package jaffle_shop --port 8081`

The hosted MCP endpoint is anonymous, rate-limited, and fixed to synthetic data. Use local MCP or your own deployment for real warehouse data, proprietary prompts, secrets, or customer credentials.

2. Follow the supported loop

agent-loop.txt

capabilities -> catalog -> discover -> inspect -> plan/build-options -> valid-values -> validate -> compile -> execute

Start with capabilities or catalog when the client has no context.
Use discover and inspect to resolve governed IDs before building Query IR.
Use plan for natural-language intents; use build-options for partial queries.
Use valid-values before categorical filters when a dimension declares a value domain.
Run validate and compile before execute.

3. Smoke the hosted MCP demo

initialize.sh

curl https://semantic-rails.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

From an MCP client, list tools and begin with capabilities, catalog, or discover. Keep response verbosity compact unless debugging requires full planner details.

4. Smoke the local HTTP API

terminal

uv run semantic-rails serve --package jaffle_shop --port 8081

discover.sh

curl -s -X POST http://127.0.0.1:8081/api/v1/discover \
  -H 'Content-Type: application/json' \
  -d '{"terms":"revenue by store","limit":5}'

plan.sh

curl -s -X POST http://127.0.0.1:8081/api/v1/plan \
  -H 'Content-Type: application/json' \
  -d '{"intent":"new customer orders over time","detail":"best"}'

compile.sh

curl -s -X POST http://127.0.0.1:8081/api/v1/compile \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "version": 1,
      "select": [
        { "expression": { "measure": "measure.jaffle.revenue_usd" }, "as": "revenue_usd" }
      ],
      "group_by": ["dimension.jaffle_store_name"],
      "time": { "temporal_role": "temporal_role.jaffle_order_time", "grain": "month" },
      "limit": 5
    }
  }'

5. Keep response size intentional

MCP validate, compile, and execute default to minimal.
HTTP defaults to compact.
Use summary or minimal for tight loops.
Use full only for debugging, alternatives, chosen paths, and relationship contracts.

6. Know what is supported

Tier	Positioning
Supported core	DuckDB local runtime, CLI, MCP stdio, MCP HTTP, stable `/api/v1/*`, package authoring, checks, validation, compile, explain, and local/customer-side execution.
Supported with guardrails	Mixed-grain rewrites, historical slicing, contextual/entity-only predicates, supported event-count conversions, Snowflake execution, and optional non-DuckDB connectors.
Experimental or out of scope	Hosted real-data execution-on-behalf, managed acceleration, billing, tenant administration, arbitrary SQL pipelines, managed materialization, and fully general nested predicate planning.

When a request falls outside the supported surface, agents should surface the structured error and recovery hints instead of inventing raw SQL.

Continue to Agent Actions for the staged public query path, or Hosted MCP for public endpoint details.