Usage¶
The MCP tools¶
One typed tool per operation. Every tool takes an optional connection naming one of the
configured connections (defaults to the sole/first one).
Queries (read-only)¶
| Tool | Arguments | Returns |
|---|---|---|
sql_query |
sql, params, max_rows, timeout |
{columns, rows, row_count, truncated} |
sql_explain |
sql, params |
the dialect's query plan |
Statements must be single and read-only (SELECT/WITH/EXPLAIN/SHOW/
DESCRIBE/PRAGMA/VALUES); values bind via :name parameters. max_rows is
clamped to the server's SQL_MAX_ROWS. EXPLAIN is unavailable on MSSQL (it has
no statement-level EXPLAIN).
Writes (gated)¶
Require the server to run with SQL_ALLOW_WRITES=True; the default is read-only and
there is no per-call override.
| Tool | Arguments | Returns |
|---|---|---|
sql_execute |
sql, params (dict, or list of dicts for executemany) |
{rowcount} |
sql_execute_script |
statements: ONE all-or-nothing transaction |
{statements, rowcounts} |
Schema reflection¶
sql_list_schemas, sql_list_tables, sql_list_views, sql_list_materialized_views,
sql_list_sequences (optional schema, limit, offset); sql_list_columns,
sql_list_indexes, sql_list_foreign_keys, sql_list_constraints, sql_table_ddl,
sql_table_comment (table, optional schema); sql_view_definition (view);
sql_sample_rows (table, limit clamped to the row cap); sql_schema_catalog
(bounded catalog of a schema).
Health and registry¶
| Tool | Returns |
|---|---|
sql_ping / sql_ping_all |
connection test and latency |
sql_server_version |
server version per dialect |
sql_active_connections |
server sessions (SQLite reports unsupported) |
sql_describe_connections / sql_connection_names / sql_default_connection / sql_resolve_connection |
configured connections, passwords redacted |
sql_pool_status / sql_capabilities |
pool state and dialect capabilities |
sql_list_dialects |
supported dialects and driver availability |
Knowledge graph¶
sql_ingest_schema (schema, include_views, include_indexes, max_objects) reflects a
schema and ingests it; it needs SQL_ALLOW_KG_INGEST=True.
The SqlApi client¶
from sql_mcp import Api
api = Api(
connections={"app": "postgresql+psycopg://svc:secret@db:5432/app"},
allow_writes=False,
max_rows=500,
timeout=30.0,
)
result = api.query("SELECT * FROM users WHERE id = :id", params={"id": 1})
print(result["rows"], result["truncated"])
print(api.list_tables(), api.table_ddl("users"))
Construct it without arguments to read the SQL_* environment (see the README
configuration table).