MCP Server for Observability

Materialize provides a built-in Model Context Protocol (MCP) endpoint that gives AI agents read-only access to the system catalog (mz_* tables) for troubleshooting and observability. The MCP interface is served directly by the database; no sidecar process or external server is required.

Endpoint: POST /api/mcp/observatory (HTTP port, default 6876)

The endpoint uses JSON-RPC 2.0 over HTTP POST and supports the MCP initialize, tools/list, and tools/call methods.

Connect to the MCP server

Step 1. Get your credentials

Step 2. Encode your credentials in Base64

MCP clients send credentials as a Base64-encoded user:password string. Run this in your terminal:

printf '<user>:<app_password>' | base64

For example:

printf 'svc-mcp-agent@mycompany.com:my_app_password_here' | base64
# Output: c3ZjLW1jcC1hZ2VudEBteWNvbXBhbnkuY29tOm15X2FwcF9wYXNzd29yZF9oZXJl

Step 3. Get your hostname

<region-id>.materialize.cloud

https://<region-id>.materialize.cloud/api/mcp/observatory

http://<host>:6876/api/mcp/observatory

Step 4. Configure your MCP client

{
  "mcpServers": {
    "materialize-observatory": {
      "type": "http",
      "url": "https://<region-id>.materialize.cloud/api/mcp/observatory",
      "headers": {
        "Authorization": "Basic <base64-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "materialize-observatory": {
      "url": "https://<region-id>.materialize.cloud/api/mcp/observatory",
      "headers": {
        "Authorization": "Basic <base64-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "materialize-observatory": {
      "url": "https://<region-id>.materialize.cloud/api/mcp/observatory",
      "headers": {
        "Authorization": "Basic <base64-token>"
      }
    }
  }
}

curl -X POST https://<region-id>.materialize.cloud/api/mcp/observatory \
  -H "Content-Type: application/json" \
  -H "Authorization: "Basic <base64-token>"" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Enabling the endpoint

The observatory endpoint is disabled by default. Enable it at runtime:

ALTER SYSTEM SET enable_mcp_observatory = true;

When the endpoint is disabled, requests return HTTP 503 (Service Unavailable).

What you can ask

After connecting an MCP-compatible AI agent (such as Claude Code, Claude Desktop, or Cursor) to the observatory endpoint, you can ask natural language questions like:

• “Why is my materialized view stale?” — The agent checks materialization lag, hydration status, replica health, and source errors.
• “Why is my cluster running out of memory?” — The agent checks replica utilization, identifies the largest dataflows, and finds optimization opportunities via the built-in index advisor.
• “Has my source finished snapshotting yet?” — The agent checks source statistics and status.
• “How much memory is my cluster using?” — The agent checks replica utilization metrics across all clusters.
• “What’s the health of my environment?” — The agent checks replica statuses, source and sink health, and resource utilization.
• “What can I optimize to save costs?” — The agent queries the index advisor for materialized views that can be dematerialized and indexes that can be dropped.

The agent translates these questions into the appropriate system catalog queries, runs them via the query_system_catalog tool, and synthesizes the results.

Tools

query_system_catalog

Execute a read-only SQL query restricted to system catalog tables (mz_*, pg_catalog, information_schema).

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
  }
}

Key system catalog tables

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

Related pages

• MCP Server for Agents
• Coding Agent Skills