Home  /  Tools and integrations  /  MCP Servers and agent skills

Developer MCP server tools

View as Markdown

Tools

query_system_catalog

Execute a read-only SQL query restricted to system catalog tables (mz_*, pg_catalog, information_schema). The tool does not take a cluster argument; the request runs on the catalog server cluster (mz_catalog_server).

💡 Tip: For system catalog lookups that can run on the mz_catalog_server cluster, prefer query_system_catalog over the query tool.
Parameter Type Required Description
sql_query string Yes SELECT, SHOW, or EXPLAIN query using only system catalog tables.

Only one statement per call is allowed. Write operations (INSERT, UPDATE, CREATE, etc.) are rejected.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  [\n    \"quickstart\",\n    \"ready\"\n  ],\n  [\n    \"mcp_cluster\",\n    \"ready\"\n  ]\n]"
      }
    ],
    "isError": false
  }
}

query

Available starting in v26.30. Execute a read-only SQL query (SELECT, SHOW, or EXPLAIN) against any object the role can access, including system catalog and user objects. You must specify a cluster to run EXPLAIN ANALYZE and queries against 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. To disable the tool, see enable_mcp_developer_query_tool.

💡 Tip: For system catalog lookups that can run on the mz_catalog_server cluster, prefer query_system_catalog over query.

Example response:

{
  "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
Freshness / lag mz_internal.mz_materialization_lag, mz_internal.mz_wallclock_global_lag_recent_history, mz_internal.mz_hydration_statuses
Memory / resources mz_internal.mz_cluster_replica_utilization, mz_internal.mz_cluster_replica_metrics
Cluster health mz_internal.mz_cluster_replica_statuses, mz_catalog.mz_cluster_replicas
Source / Sink health mz_internal.mz_source_statuses, mz_internal.mz_sink_statuses, mz_internal.mz_source_statistics
Object inventory mz_catalog.mz_materialized_views, mz_catalog.mz_sources, mz_catalog.mz_sinks, mz_catalog.mz_indexes
Optimization mz_internal.mz_index_advice, mz_catalog.mz_cluster_replica_sizes

Use SHOW TABLES FROM mz_internal or SHOW TABLES FROM mz_catalog to discover more tables.

See also

Back to top ↑