Query
Agents call MCP or HTTP. Query IR is the closed JSON contract; catalog SQL is the MCP-facing dialect over logical tables — not raw source SQL.
MCP tools
| Tool | Role |
|---|---|
how_to_use_me |
Closed contract: never, where shapes, invalidExamples. Call first. |
describe_catalog |
Logical entities and fields the agent may query. |
execute_sql |
Catalog SQL against the logical catalog. Logs SQL to stderr. |
No per-table tools. Query IR is HTTP/CLI, not an MCP tool.
HTTP /v1
| Path | Purpose |
|---|---|
GET /v1/health |
Unauthenticated probe |
GET /v1/howtouseme |
Same closed IR contract as the MCP tool |
GET /v1/catalog |
Logical catalog for the caller |
POST /v1/queries |
Execute Query IR JSON |
POST /v1/sql |
Execute catalog SQL |
curl -s http://127.0.0.1:8088/v1/howtouseme | jq .
curl -s -H "Authorization: Bearer $QLLM_AUTH_TOKEN" http://127.0.0.1:8088/v1/catalog
curl -s -X POST http://127.0.0.1:8088/v1/queries -d @query.jsonCatalog SQL vs Query IR
Query IR
Structured JSON against the catalog. Preferred for HTTP clients and goldens. Schemas live under planning/schemas/.
Catalog SQL
SQL over logical table names for MCP execute_sql and
POST /v1/sql. Still governed by the catalog, limits, and read-only rules —
not a pass-through to Postgres/MySQL dialects.
Response envelope
Successful and typed-error responses follow the shared JSON envelope (columns, rows,
meta, errors). Agents should treat typed codes (TIMEOUT,
UNSUPPORTED, VALIDATION_ERROR, …) as machine-readable — not free
text. Details:
docs/en/responses.md.
MCP transports
./qllm serve --mcp --config-dir ./my-project # STDIO
./qllm serve --mcp-http --config-dir ./my-project # Streamable HTTP + SSE
./qllm serve --http --mcp-http --config-dir ./my-project
MCP HTTP paths: /mcp (Streamable HTTP) and /sse (legacy
Inspector). Defaults bind loopback.