@thyn-ai/sqai-mcp

@thyn-ai/sqai-mcp

SQAI (Structured Query AI) as an MCP server — the three governed, deterministic, read-only structured-data tools for any MCP host (Claude Desktop, Cursor, and friends), over stdio.

The tool surface is not a fork: this server reads descriptions, Zod input schemas, and execute functions straight off the tool objects in @thyn-ai/sqai-ai-sdk. One source of truth, projected to MCP.

Install & run

# zero-config: introspection works with no environment at all
npx @thyn-ai/sqai-mcp

The server speaks newline-delimited JSON-RPC 2.0 on stdio. With zero environment it answers initialize and tools/list immediately — introspection needs no credentials. Executing any tool requires a free community login (sqai login / device registration) — fully offline thereafter; without it every tools/call returns a structured login_required error, never a crash. Sources connect lazily on the first tool call, and a connection failure comes back as a structured source_connection_failed error, never a crash.

Claude Desktop / Cursor

{
  "mcpServers": {
    "sqai": {
      "command": "npx",
      "args": ["-y", "@thyn-ai/sqai-mcp"],
      "env": {
        "SQAI_SOURCES": "[{\"data\": \"./data/sales.csv\", \"name\": \"sales\"}]"
      }
    }
  }
}

Environment (all optional):

Variable	Meaning
SQAI_SOURCES	JSON array of SqaiSourceInput: a path/URL string, an array of row objects, or { "data": …, "name": "…" }. Connects lazily.
SQAI_API_KEY	API key for licensing / API mode (semantics owned by @thyn-ai/sqai). Not needed for introspection; required for tool execution unless sqai login has cached a device key.
SQAI_DEPLOYMENT_URL	Private deployment endpoint; selects deployment mode when present.

A malformed SQAI_SOURCES fails fast at startup with a structured invalid_sources_env error on stderr — the server never serves a half-valid configuration.

The three tools

Tool	What it does
listSources	Discovery: connected sources with exact field names, types, and allowed operations; computation-catalog search; per-module function signatures.
queryData	One deterministic, read-only request — kind: "query" (aggregations, grouping, filtering over connected sources) or kind: "computation" (math over arrays; simulation modules require a seed). Large results truncate for context and stay retrievable via result_id.
explainQuery	Dry-run a queryData request: resolved plan, plan_hash, confidence, and validation without executing; or a computation-signature check with a preview invocation_hash.

All three carry the MCP annotations readOnlyHint: true, destructiveHint: false, idempotentHint: true (deterministic — plan_hash / invocation_hash prove it), openWorldHint: false.

Errors are structured payloads (status: "error", code, message, retryable, request_id) — domain outcomes like needs_clarification and rejected are normal results the model can reason about, not failures.

Licensing

Introspection (initialize / tools/list) needs no credentials. Executing any of the three tools requires a free community login (npx @thyn-ai/sqai-cli login, or sqai login — device registration) — fully offline thereafter; licensing moves a signed token, never your data. Without it, every tool call — local CSV reads included — returns a structured login_required error by design.

Links

• Product: sqai.com
• TypeScript SDK: @thyn-ai/sqai
• AI SDK tools: @thyn-ai/sqai-ai-sdk

Apache-2.0 · a Thyn product