Home  /  Tools and integrations  /  MCP Server

Agent MCP server tools

View as Markdown

Tools

get_data_products

Discovers all available data products. Returns a lightweight list with name, cluster, and description for each product.

Parameters: None.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  [\n    \"\\\"materialize\\\".\\\"mcp_schema\\\".\\\"payment_status\\\"\",\n    \"mcp_cluster\",\n    \"Given an order ID, return the current payment status.\"\n  ]\n]"
      }
    ],
    "isError": false
  }
}

get_data_product_details

Returns the full details for a specific data product, including its JSON schema with column names, types, and descriptions.

Parameter Type Required Description
name string Yes Exact name from the get_data_products list.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  [\n    \"\\\"materialize\\\".\\\"mcp_schema\\\".\\\"payment_status\\\"\",\n    \"mcp_cluster\",\n    \"Given an order ID, return the current payment status.\",\n    \"{\\\"order_id\\\": {\\\"type\\\": \\\"integer\\\", \\\"position\\\": 1}, \\\"status\\\": {\\\"type\\\": \\\"text\\\", \\\"position\\\": 3}}\"\n  ]\n]"
      }
    ],
    "isError": false
  }
}

read_data_product

Reads rows from a data product.

Parameter Type Required Description
name string Yes Fully-qualified name, e.g. "materialize"."public"."payment_status".
limit integer No Maximum rows to return. Default: 500, max: 1000.
cluster string No Cluster override. If omitted, uses the cluster from the catalog.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  [\n    1001,\n    42,\n    \"shipped\",\n    \"2026-03-26T10:30:00Z\"\n  ]\n]"
      }
    ],
    "isError": false
  }
}

query

WARNING! Enabling the query tool can impact performance, leak information via query execution errors, and, by default, allow catalog-level discovery of operational metadata through system catalog access.

Allows the agent to run arbitrary SELECT statements (including joins) against any object for which it has SELECT privileges (not just the discoverable objects). It is disabled by default.

Parameter Type Required Description
cluster string Yes Exact cluster name from the data product details.
sql_query string Yes PostgreSQL-compatible SELECT statement.

To enable the tool, set the enable_mcp_agent_query_tool configuration system parameter to true.

To prevent an agent from querying the system catalog objects (mz_catalog.*, mz_internal.*, pg_catalog.*, and information_schema.*), see Restrict query tool access to user objects only.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  [\n    \"42\",\n    \"shipped\"\n  ]\n]"
      }
    ],
    "isError": false
  }
}

Restricting query tool access to user objects only

When the query tool is enabled, a role can, by default, query any object for which it has SELECT privileges, including system catalog objects (mz_catalog.*, mz_internal.*, pg_catalog.*, and information_schema.*).

To prevent an agent role from reading system catalog objects, a superuser can set the restrict_to_user_objects parameter to true on both the functional role and each individual agent role. Setting the parameter on the functional role is recommended as a precaution in case the role is ever used directly to run queries. Because role configuration in Materialize is not inherited, the parameter must be set explicitly on each individual agent role:

ALTER ROLE mcp_agent SET restrict_to_user_objects = true;
ALTER ROLE my_agent SET restrict_to_user_objects = true;

This setting takes effect on the next connection. Once active:

  • Queries referencing system catalog objects are rejected with a permission error.
  • Data product discovery (get_data_products, get_data_product_details, read_data_product) continues to work normally.
  • The restriction cannot be bypassed by the role itself; only a superuser can change or remove it.

To remove the restriction for an agent, a superuser can reset the parameter (or set it to false):

ALTER ROLE my_agent RESET restrict_to_user_objects;
Back to top ↑