Query Tools (/mcp/query)
The tools available at the /mcp/query endpoint focus on database exploration, schema discovery, and data retrieval.
Core Database Tools
| Tool | Description |
|---|---|
list_schemas | Lists all available database schemas. |
list_tables | Lists all tables in a specific schema. |
get_constraints | Retrieves primary and foreign key constraints. |
run_sql_readonly | Executes a SQL query in read-only mode. |
explain_sql | Generates an execution plan for a SQL query. |
list_schemas
Returns all database schemas (also called databases) visible to the configured ProxySQL user.
Parameters: None.
Returns: An array of schema name strings.
list_tables
Lists all tables (and views) within a given schema.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | yes | The schema (database) name to inspect. |
Returns: An array of table/view name strings within the specified schema.
get_constraints
Retrieves primary key and foreign key constraint definitions for a table.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | yes | The schema containing the table. |
table | string | yes | The table name whose constraints should be returned. |
Returns: An object with primary_keys (array of column names) and foreign_keys (array of objects each describing referenced table and columns).
run_sql_readonly
Executes an arbitrary SQL statement in read-only mode. Statements that modify data will be rejected. ProxySQL routes the query via a read hostgroup.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sql | string | yes | The SQL statement to execute. Must be a SELECT or other read-only statement. |
schema | string | no | Default schema to use for unqualified table references. |
Returns: An object with columns (array of column names) and rows (array of arrays containing the result data).
explain_sql
Generates an execution plan for a SQL query using the backend’s EXPLAIN facility, without executing the query itself.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sql | string | yes | The SQL statement to explain. |
schema | string | no | Default schema context for the query. |
Returns: The raw EXPLAIN output as an array of rows, suitable for passing to an LLM for interpretation.
Discovery & Catalog Tools
| Tool | Description |
|---|---|
discovery.run_static | Triggers a harvest of database metadata. |
catalog.init | Initializes the MCP catalog. |
catalog.search | Full-text search over discovered tables and columns. |
catalog.get_object | Fetches details for a specific table or view. |
catalog.list_objects | Lists all discovered objects in the catalog. |
catalog.get_relationships | Lists relationships between tables. |
discovery.run_static
Triggers a full static discovery pass over all configured backend servers, harvesting schema metadata and populating the MCP Catalog. See MCP Autodiscovery for a detailed description of the two-phase process.
Parameters: None.
Returns: A run_id string identifying this discovery execution, plus a summary count of schemas, tables, and columns harvested.
catalog.init
Initialises or re-initialises the MCP Catalog database. This is typically called once during initial setup or after a major schema migration.
Parameters: None.
Returns: Confirmation that the catalog was initialised successfully.
catalog.search
Performs a full-text search over all object names, column names, and LLM-generated summaries stored in the catalog.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | The search query. |
limit | int | no | Maximum number of results to return. Defaults to 10. |
Returns: An array of matching catalog objects (tables, views, columns) with their schema path and a relevance snippet.
catalog.get_object
Fetches the full definition of a specific table or view from the catalog, including all column metadata and any LLM-generated summaries.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | yes | The schema containing the object. |
name | string | yes | The table or view name. |
Returns: An object containing column definitions (name, type, nullability, default), index definitions, foreign keys, and any stored LLM summaries or notes.
catalog.list_objects
Lists all tables and views currently stored in the catalog, optionally filtered by schema.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | no | If provided, limits results to this schema. |
Returns: An array of objects, each with schema, name, and type (table or view).
catalog.get_relationships
Lists all foreign-key relationships between tables as stored in the catalog.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | no | If provided, limits results to relationships involving tables in this schema. |
Returns: An array of relationship objects each describing the source table/column and the referenced table/column.
LLM Context & Agent Management
| Tool | Description |
|---|---|
agent.run_start | Starts a new tracking run for an AI agent. |
agent.run_finish | Marks an agent run as complete. |
agent.event_append | Appends a log event to an agent run. |
llm.summary_upsert | Stores an LLM-generated summary for a database object. |
llm.note_add | Adds a specific note or observation about the schema. |
llm.search | Semantic search over LLM-generated summaries and notes. |
agent.run_start
Creates a new agent run record, returning a run_id that should be passed to subsequent calls within the same logical agent session.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
label | string | no | Human-readable label for this run (e.g., the user’s original question). |
Returns: A run_id string.
agent.run_finish
Marks an agent run as complete and records a final status.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
run_id | string | yes | The run ID returned by agent.run_start. |
status | string | no | Final status, e.g. success or error. Defaults to success. |
Returns: Confirmation.
agent.event_append
Appends a structured log event to an active agent run, useful for recording intermediate steps or observations.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
run_id | string | yes | The active run ID. |
event_type | string | yes | A short event type label (e.g., tool_call, observation). |
payload | object | no | Arbitrary JSON payload to store with the event. |
Returns: Confirmation.
llm.summary_upsert
Stores or updates an LLM-generated natural-language summary for a catalog object (table or view).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | yes | The schema of the object being described. |
name | string | yes | The table or view name. |
summary | string | yes | The LLM-generated summary text. |
Returns: Confirmation.
llm.note_add
Adds a free-form note or observation about a schema object, supplementing or correcting automatically generated summaries.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | string | yes | The schema of the relevant object. |
name | string | yes | The table, view, or column name. |
note | string | yes | The note text. |
Returns: Confirmation and a note ID.
llm.search
Semantic search over stored LLM-generated summaries and notes.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | The natural-language query to search against stored summaries and notes. |
limit | int | no | Maximum number of results. Defaults to 10. |
Returns: An array of matching summaries/notes with their associated schema object and a similarity score.
Specialized Tools
| Tool | Description |
|---|---|
suggest_joins | Suggests potential joins between tables based on catalog metadata. |
stats.get_tool_usage | Retrieves performance statistics for MCP tools. |
suggest_joins
Analyses the catalog metadata to suggest plausible JOIN conditions between two or more tables, based on foreign key relationships and column name/type heuristics.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
tables | array of strings | yes | Two or more fully-qualified table names (e.g., ["mydb.orders", "mydb.customers"]) to suggest joins between. |
Returns: An array of suggested join conditions, each with a confidence score and the SQL fragment for the join predicate.
stats.get_tool_usage
Returns per-tool call counts and average latency statistics for the current MCP server session.
Parameters: None.
Returns: An array of objects, each containing the tool name, call count, average latency (ms), and error count.