Agent Quickstart

Local profiles under ~/.semantic_rails are developer CLI defaults only. Agent and hosted configs should pass explicit package paths and keep secrets in their own config/vault boundary.

semantic-rails serve runs one foreground server for the HTTP API and stateless Streamable HTTP at /mcp. Run it in a separate terminal and stop it with Ctrl-C. For stdio, let the MCP client launch the server from generated config. See the HTTP API and MCP setup for request headers, API-key authentication, and trusted caller context.

To connect a client to your own package, run these from the directory that holds my_package. MCP clients may start in another directory, so pass an absolute path.

claude mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"

codex mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"

uv tool install semantic-rails
"$(uv tool dir --bin)/semantic-rails" mcp setup --path "$PWD/my_package" --client claude --mcp query --install --yes

uv tool dir --bin finds the command even when uv's tool directory isn't on your PATH yet. These client commands are for macOS and Linux shells; Windows isn't covered by our checks yet. For Cursor, install the command and print the two absolute paths the config needs, then add the server to .cursor/mcp.json.

uv tool install semantic-rails
echo "$(uv tool dir --bin)/semantic-rails"
echo "$PWD/my_package"

{
  "mcpServers": {
    "semantic-rails": {
      "command": "/absolute/path/to/semantic-rails",
      "args": ["mcp", "stdio", "--path", "/absolute/path/to/my_package"]
    }
  }
}

claude mcp add --transport http semantic-rails-demo https://semantic-rails.com/mcp
codex mcp add semantic-rails-demo --url https://semantic-rails.com/mcp

Run mcp setup without --install --yes to preview a change. --mcp both adds the Architect MCP, which can edit package files. Don't run mcp setup --install through uvx: the config would point into uv's cache, which uv cache clean deletes.

Over MCP, execute takes mode="validate" or mode="sql" for the validate and compile dry runs below, and build-options is HTTP and CLI only.

discover -> plan -> execute

• discover maps business terms to governed semantic objects.
• inspect (optional) opens an object card with usage, provenance, comparison metadata, and starter patches.
• plan returns the best query call draft for natural-language intents, with a status that says whether to run it. Use detail="full" only when you need alternatives or blocked drafts.
• build-options returns legal next query choices for guided builders.
• valid-values searches categorical values for selected dimensions.
• execute is the MCP tool name (HTTP path /api/v1/query, CLI verb semantic-rails query). It validates and compiles the request, then executes it in the local or customer-operated runtime. An invalid query fails with a structured error and, where possible, recovery hints instead of running. On MCP it returns at most max_rows rows (default 200); a capped result sets truncated and warns EXECUTE_ROWS_TRUNCATED. A window (last, this, start and/or end) without a time.grain returns one total over the window, with no time column, and says so in assumptions; set time.grain for one row per period. A time with neither a grain nor a window is refused. Pass now beside the call (HTTP options.now) to pin relative windows (now). Every MCP tool and mode fits one 32,000-character response budget. Optional plans and metadata are trimmed first (omitted_fields names them); required data that still cannot fit is refused with RESULT_TOO_LARGE. Compact responses omit compiler plans.
• validate (optional dry run) returns diagnostics, repair hints, output columns, and risk metadata without executing.
• compile (optional dry run) returns SQL and plan metadata without executing. At compact or full verbosity, its response also includes an explain payload with the semantic and physical plan plus a chosen_paths map keyed by target entity ID — each entry carries selected (the chosen relationship path), candidates (every considered path), and contracts (the relationship contracts along the selected path). The CLI defaults to compact; on MCP, execute with mode: "sql" defaults to minimal, which leaves explain out, so pass verbosity: "compact" to review join paths and safety before execution.

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 discover; empty terms list every id in the package. Keep the default minimal verbosity unless debugging requires full planner details.

• MCP tools default to minimal verbosity, and plan to detail="query".
• HTTP defaults to compact.
• Use summary or minimal for tight loops.
• Use full only for debugging, alternatives, chosen paths, and relationship contracts.

DuckDB runs in every CI run. The other warehouse connectors, Snowflake included, have dialect-level test coverage; live runs need credentials and happen on demand, not in every CI run.

Since engine 0.3.2 the query MCP has one interface, v2, which initialize reports as serverInfo.version. Setting SEMANTIC_RAILS_MCP_INTERFACE=v1 fails, and calling a v1 tool returns UNKNOWN_MCP_TOOL.

To move a v1 client to v2:

• validate becomes execute with mode: "validate", and compile becomes execute with mode: "sql".
• segment-validate, segment-explain and segment-preview become segment with action validate, explain or preview; pass verbosity: "full" for the whole response.
• catalog becomes discover with empty terms.
• capabilities and build-options have no MCP tool: draft the call with plan. The HTTP API keeps both, and the CLI keeps build-options.
• Defaults are smaller: discover and inspect return slim cards (verbosity: "compact" for v1's), and plan returns detail: "query" (detail: "best" for v1's).