DeepSQL CLI + MCP server

The @deepsql/mcp package ships two things in one binary:

• deepsql — a CLI for talking to a self-hosted DeepSQL backend from a terminal (auth, connections, SQL execution, plan analysis, index suggestions, slow-query analyses, admin ops).
• deepsql mcp — a stdio MCP server that exposes the same backend to editor agents (Claude Code, Cursor, Codex, Claude Desktop) so they can query and reason about the user's databases.

Both share one auth file (~/.config/deepsql/auth.json, mode 0600). Log in once with deepsql login; the MCP server uses the same token automatically — no token needs to be embedded in your editor's config.

Install

npm install -g @deepsql/mcp@latest
deepsql --version

Requires Node ≥ 20.

Quick start

deepsql login --url https://your-deepsql-host.example.com
deepsql connections list
deepsql connections use <connection-name>
deepsql query "SELECT 1 AS ok"

Wire into your editor (one command per editor)

The installer writes the MCP server entry into the editor's config AND installs a "DBA consult" skill that auto-triggers when the user asks the agent to do database work:

deepsql mcp config --install --for claude-code      # via `claude mcp add --scope user`
deepsql mcp config --install --for claude-desktop   # macOS ~/Library/.../Claude/...
deepsql mcp config --install --for cursor           # ~/.cursor/mcp.json + ~/.cursor/rules/deepsql.mdc
deepsql mcp config --install --for codex            # ~/.codex/config.toml + ~/.codex/AGENTS.md

Pass --print to see what would be written without touching disk. Pass --no-skill to install only the MCP entry. Pass --force to overwrite a stale entry. See deepsql mcp --help for details.

Restart the editor for the entry to load.

What the MCP server exposes

10 tools, all read-only at the schema/retrieval layer and policy-gated at the SQL layer:

| Tool | Purpose | |---|---| | list_connections | Connections this token has access to | | get_schema | Cached schema metadata (tables, columns, FKs, types) | | get_database_objects | Tables, views, functions, procedures | | get_brain_context | Retrieval brain: tables/columns/FKs/training docs/rules for a question | | list_business_rules | Active business rules and SQL guardrails for a connection | | get_relationships | Inferred + validated foreign keys with confidence scores | | get_anti_patterns | Schema-level or query-level anti-patterns | | analyze_slow_queries | Recent slow queries with fingerprints, durations, examples | | execute_sql | Run any SQL — backend enforces role-based policy (developers read-only, admins can mutate with two-step confirm) | | analyze_query_plan | AI-enriched plan analysis (parsed plan tree, performance issues, index recommendations, written summary that uses the connection's schema + business rules) |

EXPLAIN and EXPLAIN ANALYZE are just SQL — pass them as the query to execute_sql. For the AI-enriched plan analysis with the LLM-written summary, use analyze_query_plan.

Runtime guidance for agents

CLAUDE.md (bundled in this package, at node_modules/@deepsql/mcp/CLAUDE.md after install) is the runtime guide for editor agents that have these tools loaded. It covers the "DBA consult" pattern, decision tree, hard rules around the role-gated mutation flow, and common foot-guns. The installer also drops a shortened, trigger-focused version of that guide as a native skill so the pattern fires automatically on phrases like "add a table", "write a migration", "design a schema", "query the database".

Agent-driven setup (one paste)

For a fresh customer install, paste AGENT-SETUP.md (bundled at node_modules/@deepsql/mcp/AGENT-SETUP.md) into Claude Code / Cursor / Codex. The agent walks the user through install, login, connection registration, editor integration, and end-to-end validation in ~5 minutes.

Manual install (only if you don't want the CLI shim)

If you'd rather skip the deepsql mcp config --install flow and wire the editor config by hand, see the example files bundled with this package: claude_desktop_config.customer.example.json and codex_config.customer.example.toml. The token-embedded shape in those examples still works, but deepsql mcp config --install is the recommended path now.

Run the server directly (advanced)

deepsql mcp                # uses the saved profile + auth token
npx -y @deepsql/mcp        # one-off invocation without install

Both work; the CLI shim is preferred because it shares the saved profile and never asks you to paste a token into editor config.

Environment variables

| Variable | Required | Used by | Example | |----------|----------|---------|---------| | DEEPSQL_API_BASE_URL | for npx-style invocation | deepsql mcp if no saved profile | https://customer-deepsql.example.com/api/ | | DEEPSQL_AUTH_TOKEN | for npx-style invocation | bearer for backend; deepsql login writes one to the profile file | dsql_mcp_… | | DEEPSQL_MCP_USER_ID | no | identifies the editor that invoked the MCP server in audit logs | claude-desktop / cursor-mcp / codex-mcp | | DEEPSQL_CALLER_AGENT | no | overrides the CLI's audit identity when an agent shells out to deepsql | claude-code | | DEEPSQL_MCP_TIMEOUT_MS | no | per-request timeout for MCP server calls | 120000 |

If deepsql login has been run, both the CLI and the spawned MCP server pick up DEEPSQL_API_BASE_URL + DEEPSQL_AUTH_TOKEN from ~/.config/deepsql/auth.json automatically — you don't need to set the env vars for either.