MCP Server for Developers

View as Markdown

PREVIEW This feature is in public preview. It is under active development and may have stability or performance issues. It isn't subject to our backwards compatibility guarantees.

Materialize provides a built-in materialize-developer Model Context Protocol (MCP) server (/api/mcp/developer, port 6876) for troubleshooting and observability. The server is provided directly by Materialize; no sidecar process or external server is required.

Overview

You can connect an MCP-compatible client (such as Claude Code, Claude Desktop, or Cursor) to the MCP server to:

Ask questions about the Materialize system
- Why is my materialized view stale?
- How much memory is my cluster using?
Run queries on your objects (Available starting in v26.30)
- Using the quickstart cluster, SELECT * from my_mat_view;
- Using the quickstart cluster, examine the memory usage of my_mat_view with skew.

Connect to the MCP server

There are two ways to authenticate to the materialize-developer MCP server:

OAuth: Starting in v26.30, your MCP client can sign you in through your browser; no token to generate or store. Available for Cloud and for Self-Managed using SSO.
Token-based: You provide Base64-encoded credentials (the MCP token) to the client. Available for Cloud, Self-Managed, and the Emulator.

Method 1: OAuth

Available starting in v26.30

NOTE: The OAuth method is available for Cloud and for Self-Managed deployments using SSO. For the Emulator (or Self-Managed not using SSO), use Method 2: Token-based authentication.

Step 1. Get your MCP server URL

To connect, the MCP-compatible client needs the materialize-developer MCP server URL: <baseURL>/api/mcp/developer.

Log in to the Materialize Console.
Click the Connect link (lower-left corner) to open the Connect modal and click on the MCP Server tab.
In the Connect your client section, click on the Developer tab.

You can find your materialize-developer MCP server URL <baseURL>/api/mcp/developer as part of the code block.

If using Claude Code as your MCP-compatible client, you can copy the code block wholesale for the next step.

Self-Managed deployments using OAuth require SSO, which uses TLS. Get your MCP server URL from the Materialize Console:

Log in via the Materialize Console.
Click the Connect link (lower-left corner) to open the Connect modal and click on the MCP Server tab.
In the Connect your client section, click on the Developer tab.

You can find your materialize-developer MCP server URL <baseURL>/api/mcp/developer as part of the code block.

If using Claude Code as your MCP-compatible client, you can copy the code block wholesale for the next step.

Step 2. Configure your MCP client

Once you have your materialize-developer MCP server URL, you can configure your MCP client. The materialize-developer MCP server URL has the form: <baseURL>/api/mcp/developer.

Add the materialize-developer MCP server as local-scoped server (i.e., the configurations are stored in ~/.claude.json):

claude mcp add --transport http materialize-developer \
  <baseURL>/api/mcp/developer

Update the <baseURL> placeholder with your value:

Deployment	`<baseURL>`
Cloud	Replace with your value
Self-Managed	Replace with your value

Restart Claude Code. On first connection, your browser opens to complete sign-in and connect.
Upon successful connection, you can Start asking questions.

To configure Claude Desktop/Chrome, add a custom connector. The exact steps depend on your Claude plan; for example:

Organization settings → Connectors → Add → Custom → Web, or
Customize → Connectors → + → Add custom connector.

Refer to the Add a custom connector section of the Get started with custom connectors using Remote MCP guide to get the exact steps for your plan. For the Remote MCP server URL field, enter your materialize-developer MCP server URL.

For additional information, including network requirements and security and privacy concerns, see the Get started with custom connectors using Remote MCP article.

Add the materialize-developer MCP server entry to your local MCP settings file (~/.cursor/mcp.json).

When merging into an existing mcpServers object, remember to add commas between entries.
If the mcpServers field does not already exist, add it as well.

{
  "mcpServers": {
    "materialize-developer": {
      "url": "<baseURL>/api/mcp/developer"
    }
  }
}

Update the <baseURL> placeholder with your value:

Deployment	`<baseURL>`
Cloud	Replace with your value
Self-Managed	Replace with your value

Restart Cursor. On first connection, your browser opens to complete sign-in and connect.
Upon successful connection, you can Start asking questions.

Method 2: Token-based authentication

When connecting to the MCP server, the MCP-compatible client needs:

The Base64-encoded credentials (i.e., the MCP token).
The materialize-developer MCP server URL: <baseURL>/api/mcp/developer.

Step 1. Get your MCP token

The MCP token is your base64-encoded credentials. Prefer using a personal app password over encoding your account credentials as the token is only base64-encoded and not encrypted.

Log in to the Materialize Console.
Get your base64-encoded token for your personal app.
- If you already have an MCP token for your personal app, copy the token.
- If you want to create a new personal app password to use, the MCP token is generated when you create the new app password (Create New → App Password). Copy the token as you will use the token to connect. Once you navigate away, the token will not display again.
- If using an existing personal app password, manually generate the base64-encoded token.
```
printf '<user>:<app_password>' | base64 -w0
```

The MCP token is your base64-encoded credentials. Prefer using a separate role’s login credentials over encoding your own credentials as the token is only base64-encoded and not encrypted.

For the MCP token, you can use either an existing or new app login role with password.
- To use an existing login role with password, go to the next step.
- To create a new login role with password:
```
CREATE ROLE my_dev_agent LOGIN PASSWORD '<your_app_password>';
```
Encode your role’s credentials <role>:<password> in Base64 to create the MCP token, replacing <your_app_password> with the actual password:
```
printf 'my_dev_agent:<your_app_password>' | base64
```

To connect to the MCP server for your Emulator, you can create a role for your specific AI agent or use the default materialize user:

You can create a role for your specific AI agent (the Emulator does not support the LOGIN PASSWORD option):
```
CREATE ROLE my_dev_agent;
```
Base64-encode your agent role’s credentials <role>:<password> to create the MCP token (the Emulator does not support passwords):
```
printf 'my_dev_agent:' | base64
```

Step 2. Get your MCP server URL

To connect, the MCP-compatible client needs the materialize-developer MCP server URL: <baseURL>/api/mcp/developer.

Log in to the Materialize Console.
Click the Connect link (lower-left corner) to open the Connect modal and click on the MCP Server tab.
In the Connect your client section, click on the Developer tab.

You can find your materialize-developer MCP server URL <baseURL>/api/mcp/developer as part of the code block.

If using Claude Code as your MCP-compatible client, you can copy the code block wholesale for the next step.

If your Self-Managed deployment is using TLS:

Log in via the Materialize Console.
Click the Connect link (lower-left corner) to open the Connect modal and click on the MCP Server tab.
In the Connect your client section, click on the Developer tab.

You can find your materialize-developer MCP server URL <baseURL>/api/mcp/developer as part of the code block.

If using Claude Code as your MCP-compatible client, you can copy the code block wholesale for the next step.

If your Self-Managed deployment is not using TLS:

Find your deployment’s host name to determine your materialize-developer MCP URL:
- For your Self-Managed Materialize deployment in AWS/GCP/Azure, the hostname is the load balancer address. If deployed via Terraform, run the Terraform output command for your cloud provider:
```
# AWS
terraform output -raw nlb_dns_name

# GCP
terraform output -raw balancerd_load_balancer_ip

# Azure
terraform output -raw balancerd_load_balancer_ip
```
- For local kind clusters, use port forwarding and localhost is your hostname:
```
kubectl port-forward svc/<instance-name>-balancerd 6876:6876 -n materialize-environment
```
Determine the value of your MCP URL using your hostname:
```
http://<host>:6876/api/mcp/developer
```
where http://<host>:6876 is your base URL.

For the Emulator, your MCP URL is:

http://localhost:6876/api/mcp/developer

where http://localhost:6876 is your base URL.

Step 3. Configure your MCP client

WARNING! When saving your credentials or other sensitive information in a config file, do not commit these files to version control or share them publicly.

Add the materialize-developer MCP server as local-scoped server (i.e., the configurations are stored in ~/.claude.json):

claude mcp add --transport http materialize-developer \
  <baseURL>/api/mcp/developer \
  --header "Authorization: Basic <mcp-token>"

Update the <baseURL> and <mcp-token> placeholders with your values:

Deployment	`<baseURL>`	`<mcp-token>`
Cloud	Replace with your value	Replace with your value
Self-Managed	Replace with your value	Replace with your value
Emulator	`http://localhost:6876`	Replace with your value

Restart Claude Code to pick up the new setting.
Upon successful connection, you can Start asking questions.

Add the materialize-developer MCP server entry to your Claude Desktop configuration (claude_desktop_config.json).

When merging into an existing mcpServers object, remember to add commas between entries.
If the mcpServers field does not already exist, add it as well.
For older Claude Desktop versions, you may need to include the transport "type": "http", as well as part of the materialize-developer entry.

{
  "mcpServers": {
    "materialize-developer": {
      "url": "<baseURL>/api/mcp/developer",
      "headers": {
        "Authorization": "Basic <mcp-token>"
      }
    }
  }
}

Update the <baseURL> and <mcp-token> placeholders with your values:

Deployment	`<baseURL>`	`<mcp-token>`
Cloud	Replace with your value	Replace with your value
Self-Managed	Replace with your value	Replace with your value
Emulator	`http://localhost:6876`	Replace with your value

Restart Claude Desktop to pick up the new setting.
Upon successful connection, you can Start asking questions.

Add the materialize-developer MCP server entry to your local MCP settings file (~/.cursor/mcp.json).

When merging into an existing mcpServers object, remember to add commas between entries.
If the mcpServers field does not already exist, add it as well.

{
  "mcpServers": {
    "materialize-developer": {
      "url": "<baseURL>/api/mcp/developer",
      "headers": {
        "Authorization": "Basic <mcp-token>"
      }
    }
  }
}

Update the <baseURL> and <mcp-token> placeholders with your values:

Deployment	`<baseURL>`	`<mcp-token>`
Cloud	Replace with your value	Replace with your value
Self-Managed	Replace with your value	Replace with your value
Emulator	`http://localhost:6876`	Replace with your value

Restart Cursor to pick up the new setting.
Upon successful connection, you can Start asking questions.

Any MCP-compatible client can connect by sending JSON-RPC 2.0 requests; update the <baseURL> and <mcp-token> placeholders with your values:

curl -X POST <baseURL>/api/mcp/developer \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <mcp-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Start asking questions

💡 Tip: When the agent reads your user objects with the query tool, an ontology table of curated join relationships in your schema helps it confirm exact join keys before writing multi-table SQL.

Once connected to the MCP server, you can ask natural language questions like:

Question	What the agent does	Tool
Why is my materialized view stale?	Checks materialization lag, hydration status, replica health, and source errors. Optionally runs `EXPLAIN ANALYZE MEMORY` on the materialized view.	`query_system_catalog`, plus `query` if the agent needs `EXPLAIN ANALYZE`
Why is my cluster running out of memory?	Checks replica utilization, identifies the largest dataflows, and finds optimization opportunities via the built-in index advisor.	`query_system_catalog`, plus `query` for `EXPLAIN ANALYZE MEMORY`
Has my source finished snapshotting yet?	Checks source statistics and status.	`query_system_catalog`
How much memory is my cluster using?	Checks replica utilization metrics across all clusters.	`query_system_catalog`
What’s the health of my environment?	Checks replica statuses, source and sink health, and resource utilization.	`query_system_catalog`
What can I optimize to save costs?	Queries the index advisor for materialized views that can be dematerialized and indexes that can be dropped.	`query_system_catalog`
Using the `quickstart` cluster, examine the memory usage of `my_mat_view` with skew.	Runs `EXPLAIN ANALYZE MEMORY WITH SKEW` on the materialized view to report its memory usage and highlight data skew across workers.	`query` for `EXPLAIN ANALYZE MEMORY WITH SKEW`

The agent picks the appropriate tool for each question. Most catalog lookups run on the catalog server cluster via query_system_catalog; query (available starting in v26.30) is used when the question needs a specific cluster (for example, EXPLAIN ANALYZE against a materialized view or index, or reading user objects).

Privileges

The privileges required to use the materialize-developer MCP server are:

USAGE on system catalog schemas and SELECT on system catalog objects. These privileges are granted by default.
If agents also need access to replica-specific metrics from mz_introspection, USAGE privileges on the corresponding cluster.

MCP Server for Developers

Overview

Connect to the MCP server

Method 1: OAuth

Step 1. Get your MCP server URL

Step 2. Configure your MCP client

Method 2: Token-based authentication

Step 1. Get your MCP token

Step 2. Get your MCP server URL

Step 3. Configure your MCP client

Start asking questions

Privileges

Related pages