Query Tools (/mcp/query)
ProxySQL v4.0.10 advertises the following 29 released tools on /mcp/query. The Required and Optional
columns reproduce the released inputSchema: required properties created by the common schema helper are
advertised as strings, even for identifiers that the implementation later resolves numerically. Call
list_targets first and carry its target_id through discovery, catalog, query, agent, and LLM calls.
MCP query rules are evaluated only for run_sql_readonly and explain_sql; they are not a universal filter for
the other 27 tools or for other MCP endpoints. Several catalog, discovery, agent, and LLM tools write
mcp_catalog.db, so protect the Query token even when backend SQL is read-only.
Inventory, sampling, SQL, and discovery
| Tool | Required | Optional | Released behavior |
|---|---|---|---|
list_targets | None | None | Lists logical targets, descriptions, capabilities, and the default target. |
list_schemas | None | page_token (string), page_size (integer), target_id (string) | Lists catalog schemas for the selected or default target. |
list_tables | schema | page_token (string), page_size (integer), name_filter (string), target_id (string) | Lists backend tables for the resolved executable target. |
get_constraints | schema | table (string) | Advertised for compatibility but returns a deprecation error directing callers to catalog.get_relationships. |
sample_rows | schema, table | columns (string), where (string), order_by (string), limit (integer) | Advertised in v4.0.10, but no released execution branch exists; invocation returns Unknown tool. |
sample_distinct | schema, table, column | where (string), limit (integer) | Advertised in v4.0.10, but no released execution branch exists; invocation returns Unknown tool. |
run_sql_readonly | sql | schema (string), target_id (string), max_rows (integer), timeout_sec (integer) | Resolves an executable target, applies MCP query rules, rejects non-read-only/dangerous SQL, executes it, and records digest/tool statistics. The direct max_rows and timeout_sec arguments are parsed but not enforced in this release; an applicable query rule can rewrite/block/short-circuit and supply a timeout value. |
explain_sql | sql | schema (string), target_id (string) | Applies MCP query rules and the same read-only/dangerous-SQL validation, then executes backend EXPLAIN. |
suggest_joins | schema, table_a | table_b (string), max_candidates (integer) | Returns a deprecation error directing callers to catalog.get_relationships. |
find_reference_candidates | schema, table, column | max_tables (integer) | Returns a deprecation error directing callers to catalog.get_relationships. |
discovery.run_static | target_id | schema_filter (string), notes (string) | Runs the protocol-aware static harvester for one executable target and returns its discovery run statistics. |
Catalog
| Tool | Required | Optional | Released behavior |
|---|---|---|---|
catalog.init | None | sqlite_path (string) | Reports the catalog as initialized; omission uses the handler’s configured database path. |
catalog.search | target_id, run_id, query | limit (integer), object_type (string), schema_name (string) | FTS5 search over discovered objects in one target/run. |
catalog.get_object | target_id, run_id | object_id (integer), object_key (string), include_definition (boolean), include_profiles (boolean) | Fetches one object selected by object_id or object_key. |
catalog.list_objects | target_id, run_id | schema_name (string), object_type (string), order_by (string), page_size (integer), page_token (string) | Returns a filtered, ordered page of objects. |
catalog.get_relationships | target_id, run_id | object_id (integer), object_key (string), include_inferred (boolean), min_confidence (number) | Returns foreign keys, view dependencies, and optionally inferred relationships for one object. |
run_id may be a numeric discovery run or a schema name resolvable within the same target_id. For the exact
catalog persistence model and return contracts, see MCP Catalog.
Agent-run tracking
| Tool | Required | Optional | Released behavior |
|---|---|---|---|
agent.run_start | target_id, run_id, model_name | prompt_hash (string), budget (object) | Starts an LLM-agent run bound to a discovery run. |
agent.run_finish | agent_run_id, status | error (string) | Finishes an agent run with success/failure status and an optional error. |
agent.event_append | agent_run_id, event_type, payload | None | Appends a trace event. The released schema advertises payload as a required string. |
LLM memory and semantic artifacts
| Tool | Required | Optional | Released behavior |
|---|---|---|---|
llm.summary_upsert | target_id, agent_run_id, run_id, object_id, summary | confidence (number), status (string), sources (object) | Creates or updates the structured semantic summary for an object. |
llm.summary_get | target_id, run_id, object_id | agent_run_id (integer), latest (boolean) | Retrieves an object’s summary, optionally for one agent run or the latest entry. |
llm.relationship_upsert | target_id, agent_run_id, run_id, child_object_id, child_column, parent_object_id, parent_column, confidence | rel_type (string), evidence (object) | Stores an LLM-inferred relationship with confidence and evidence. |
llm.domain_upsert | target_id, agent_run_id, run_id, domain_key | title (string), description (string), confidence (number) | Creates or updates a semantic domain. |
llm.domain_set_members | target_id, agent_run_id, run_id, domain_key, members | None | Replaces the domain’s members. The released schema advertises members as a required string. |
llm.metric_upsert | target_id, agent_run_id, run_id, metric_key, title | description (string), domain_key (string), grain (string), unit (string), sql_template (string), depends (object), confidence (number) | Creates or updates a metric/KPI definition. |
llm.question_template_add | target_id, run_id, title, question_nl, template | agent_run_id (integer), example_sql (string), related_objects (array), confidence (number) | Adds a natural-language question template and associated structured query plan. |
llm.note_add | target_id, agent_run_id, run_id, scope, body | object_id (integer), domain_key (string), title (string), tags (array) | Stores a durable scoped note. |
llm.search | target_id, run_id | query (string), limit (integer), include_objects (boolean) | Searches LLM artifacts; an empty query lists question templates, while a non-empty query can include complete related-object schemas. |
Tool-usage statistics
| Tool | Required | Optional | Released behavior |
|---|---|---|---|
stats.get_tool_usage | None | None | Returns in-memory Query-handler invocation counts and timing grouped by endpoint, tool, and schema context. |
Use tools/list against the running endpoint to inspect the same registry. SQL/tool usage is also exposed through
the MCP Stats tables; rule-hit statistics are documented with
MCP configuration tables.