Module mcp 

Model Context Protocol (MCP) HTTP handlers.

Exposes Materialize data products to AI agents via JSON-RPC 2.0 over HTTP POST.

Endpoints

• /api/mcp/agents - User data products for customer AI agents
• /api/mcp/observatory - System catalog (mz_*) for troubleshooting

Tools

Agents: get_data_products, get_data_product_details, query Observatory: query_system_catalog

Data products are discovered via mz_internal.mz_mcp_data_products system view.

Modules

error_codes 🔒

JSON-RPC 2.0 error codes.

Structs

Capabilities 🔒

ClientInfo 🔒

ContentBlock 🔒

GetDataProductDetailsParams 🔒

InitializeParams 🔒

InitializeResult 🔒

McpError 🔒

McpRequest 🔒

JSON-RPC 2.0 request. Requests have id; notifications don’t.

McpResponse 🔒

QueryParams 🔒

QuerySystemCatalogParams 🔒

ReadDataProductParams 🔒

ServerInfo 🔒

TableReferenceCollector 🔒

Collects table references from SQL AST with their schema qualification.

ToolAnnotations 🔒

MCP 2025-11-25 tool annotations that describe tool behavior. These hints help clients make trust and safety decisions.

ToolContentResult 🔒

ToolDefinition 🔒

ToolsListResult 🔒

Enums

McpEndpointType 🔒

McpMethod 🔒

MCP method variants with their associated parameters.

McpRequestError 🔒

MCP request errors, mapped to JSON-RPC error codes.

McpResult 🔒

Typed MCP response results.

ToolsCallParams 🔒

Tool call parameters, deserialized via adjacently tagged enum. Serde maps name to the variant and arguments to the variant’s data.

Constants

DETAILS_QUERY_PREFIX 🔒

DISCOVERY_QUERY 🔒

JSONRPC_VERSION 🔒

JSON-RPC protocol version used in all MCP requests and responses.

MAX_READ_LIMIT 🔒

Maximum number of rows that can be returned by read_data_product.

MCP_PROTOCOL_VERSION 🔒

MCP protocol version returned in the initialize response. Spec: https://modelcontextprotocol.io/specification/2025-11-25

MCP_REQUEST_TIMEOUT 🔒

Maximum time an MCP tool call can run before the HTTP response is returned. Note: this returns a clean JSON-RPC error to the caller, but the underlying query may continue running on the cluster until it completes or is cancelled separately (see database-issues#9947 for SELECT timeout gaps).

READ_ONLY_ANNOTATIONS 🔒

Annotations for all MCP tools: read-only, non-destructive, idempotent.

Functions

default_read_limit 🔒

execute_query 🔒

execute_sql 🔒

Execute SQL via execute_request from sql.rs.

format_rows_response 🔒

Serialize rows to JSON and enforce the response size cap.

get_data_product_details 🔒

get_data_products 🔒

handle_initialize 🔒

handle_mcp_agents

Agents endpoint: exposes user data products.

handle_mcp_method 🔒

handle_mcp_method_not_allowed

MCP 2025-11-25 requires servers to return 405 for GET requests on endpoints that only support POST.

handle_mcp_observatory

Observatory endpoint: exposes system catalog (mz_*) only.

handle_mcp_request 🔒

handle_mcp_request_inner 🔒

handle_tools_call 🔒

handle_tools_list 🔒

query_system_catalog 🔒

read_data_product 🔒

Read rows from a data product. Issues a single read-only query.

safe_data_product_name 🔒

Parses a data product name and returns it safely quoted for SQL interpolation.

validate_origin 🔒

Validates the Origin header to prevent DNS rebinding attacks (MCP 2025-11-25). Returns Some(403) if the Origin is present but doesn’t match the Host. Returns None if the Origin is absent (non-browser client) or valid.

validate_readonly_query 🔒

Validates query is a single SELECT, SHOW, or EXPLAIN statement.

validate_system_catalog_query 🔒

Validates that a query only references system catalog tables.