Skip to content

docs/mcp: document developer query tool #36955

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bobbyiliev wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs/mcp: document developer query tool #36955

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/user/content/integrations/mcp-server/mcp-developer-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ endpoint:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `enable_mcp_developer` | `true` | Enable or disable the `/api/mcp/developer` endpoint. When the endpoint is disabled, requests return HTTP 503 (Service Unavailable). |
| `enable_mcp_developer_query_tool` | `true` | Enable or disable the `query` tool on the developer endpoint. When disabled, the tool is hidden from `tools/list` and calls return an error. `query_system_catalog` remains available. |
| `mcp_max_response_size` | `1000000` | Maximum response size in bytes. Queries exceeding this limit return an error. |

## Disabling the endpoint
Expand Down
40 changes: 39 additions & 1 deletion doc/user/content/integrations/mcp-server/mcp-developer-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ menu:
### `query_system_catalog`

Execute a read-only SQL query restricted to system catalog tables (`mz_*`,
`pg_catalog`, `information_schema`).
`pg_catalog`, `information_schema`). No cluster argument; prefer this for
catalog lookups that do not need a cluster to run on.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
Expand All @@ -41,6 +42,43 @@ Only one statement per call is allowed. Write operations (`INSERT`, `UPDATE`,
}
```

### `query`

Execute a read-only SQL query (`SELECT`, `SHOW`, or `EXPLAIN`) against any
object the role can access, including system catalog and user objects. A
cluster is required, which is what enables `EXPLAIN ANALYZE` and queries
against indexed user objects.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster` | string | Yes | Exact cluster name the query should run on. |
| `sql_query` | string | Yes | `SELECT`, `SHOW`, or `EXPLAIN` statement. |

Only one statement per call is allowed. Write operations (`INSERT`, `UPDATE`,
`CREATE`, etc.) are rejected. The tool is hidden when the operator has
disabled it via [`enable_mcp_developer_query_tool`](/integrations/mcp-server/mcp-developer-config/).

For pure system catalog lookups that do not need a cluster, prefer
[`query_system_catalog`](#query_system_catalog).

**Example response:**

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "[\n [\n \"Explained Query (fast path):\\n →Constant (1 rows)\\n\\nTarget cluster: quickstart\\n\"\n ]\n]"
}
],
"isError": false
}
}
```

### Key system catalog tables

| Scenario | Tables |
Expand Down
9 changes: 6 additions & 3 deletions doc/user/content/integrations/mcp-server/mcp-developer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,9 +266,12 @@ Once connected to the MCP server, you can ask natural language questions like:
| **What can I optimize to save costs?** | Queries the index advisor for materialized views that can be dematerialized and indexes that can be dropped. |

The agent translates natural language questions into the appropriate system
catalog queries, uses the [`query_system_catalog`
tool](/integrations/mcp-server/mcp-developer-tools/#query_system_catalog) to run
those queries, and synthesizes the results.
catalog queries and runs them via either the
[`query_system_catalog`](/integrations/mcp-server/mcp-developer-tools/#query_system_catalog)
tool (catalog lookups with no cluster needed) or the
[`query`](/integrations/mcp-server/mcp-developer-tools/#query) tool
(`EXPLAIN ANALYZE` and read-only queries against user objects, both of which
require a cluster), then synthesizes the results.

## Privileges

Expand Down
Loading