Principle:MaterializeInc Materialize MCP Tool Discovery

Overview

The MCP Tool Discovery principle describes how the Materialize MCP server dynamically discovers indexes in a Materialize catalog and exposes them as Model Context Protocol (MCP) tools. Rather than requiring manual tool definitions, the server derives the complete tool inventory at runtime by querying the system catalog, and keeps it current through background subscriptions to catalog changes.

Principle

Every Materialize index that a connected role is authorized to SELECT from, and whose cluster it can USAGE, is automatically surfaced as an MCP tool. The indexed columns become the tool's input schema and the remaining view columns become the tool's output schema.

Motivation

Static tool registrations create a maintenance burden: each new index or schema change requires a corresponding update to the MCP tool definitions. By deriving tools directly from the Materialize catalog, the server achieves:

• Zero-configuration tool registration -- New indexes become available as tools without any server changes.
• Permission-aware visibility -- Tools only appear for roles authorized to access the underlying data, enforcing Materialize's existing access control model.
• Schema fidelity -- Input and output schemas are generated from the actual column types, eliminating drift between the tool definition and the database schema.

Mechanism

Catalog Query

On startup, the server executes a SQL query (loaded from tools.sql) against the Materialize system catalog. This query identifies all indexes whose:

• Underlying view is accessible via SELECT by the connected role.
• Cluster is accessible via USAGE by the connected role.

For each qualifying index, the query returns metadata including the database, schema, object name, cluster, indexed columns (inputs), and remaining columns (outputs).

Tool Construction

Each discovered index is mapped to an MzTool instance:

Index Attribute	MCP Tool Property
Index name	Tool name
Indexed columns	inputSchema (JSON Schema)
Non-indexed view columns	outputSchema (JSON Schema)
View description	Tool description
Cluster	Used at call time for session routing

All generated tools carry readOnlyHint=True annotations, signaling to clients that invoking the tool will not modify any state.

Live Subscription

After the initial catalog load, the MzClient starts a background asyncio.Task that subscribes to catalog changes. When indexes are created, dropped, or modified, the tool list is refreshed and the server emits a tools_changed notification to connected MCP clients.

The tool dictionary is protected by an aiorwlock.RWLock:

• Read lock is held during call_tool operations, allowing concurrent tool execution.
• Write lock is held during catalog refreshes, ensuring consistent updates.

Tool Invocation

When a client calls a tool:

1. The server validates the tool name against the current catalog.
2. The session is switched to the appropriate cluster (SET CLUSTER = ...).
3. A parameterized SELECT is executed against the indexed view, using the supplied inputs as WHERE clause predicates on the indexed columns.
4. The first matching row is returned, excluding columns whose values were already supplied as inputs.

If a tool is not found (e.g., it was dropped between list_tools and call_tool), a MissingTool exception is raised and a tools_changed notification is sent to prompt the client to refresh.

Agent Variant

The MCP Materialize Agents server extends this principle with additional structure:

• Uses Pydantic models (DataProduct) to provide richer input descriptions to AI agents.
• Includes a system prompt (system_prompt.md) that teaches agents how to discover and use the available tools.
• Leverages the FastMCP framework for streamlined tool registration.

Trade-offs

Benefit	Consideration
Automatic tool discovery	Tool names and schemas may change without notice when catalog objects are modified
Permission-based filtering	Clients with different roles see different tool sets, which may complicate caching
Live subscription updates	Background subscription adds a persistent database connection per server instance

Related Pages

• Implementation:MaterializeInc_Materialize_MCP_Server
• Implementation:MaterializeInc_Materialize_MCP_Agents