MCP Server for Developers

1. Log in to the Materialize Console.

2. Click the Connect link (lower-left corner) to open the Connect modal and click on the MCP Server tab.

   

3. To get your base64-encoded token:

   • If you want to create a new personal app password to use, click on the Generate personal MCP token to generate a new personal app token for the MCP Server. 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
     

4. 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.

1. You can connect using either an existing or new 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>';
     

2. 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
   

3. Find your deployment’s host name to determine your materialize-developer MCP URL:

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

   • For your Self-Managed Materialize deployment in AWS/GCP/Azure, the <host> is the load balancer address. If deployed viaTerraform,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 use localhost for <host>:

     kubectl port-forward svc/<instance-name>-balancerd 6876:6876 -n materialize-environment
     

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:

1. You can create a role for your specific AI agent (the Emulator does not support the LOGIN PASSWORD option):

   CREATE ROLE my_dev_agent;
   

2. Encode your agent role’s credentials <role>:<password> in Base64 to create the MCP token (the Emulator does not support passwords):

   printf 'my_dev_agent:' | base64
   

3. For the Emulator, you will use http://localhost:6876 as the <baseURL> portion of the MCP URL:

   <baseURL>/api/mcp/developer
   

1. 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 (format: https://<region-id>.materialize.cloud)	Replace with your value
   Self-Managed	Replace with your value (format: http://<host>:6876)	Replace with your value
   Emulator	http://localhost:6876	Replace with your value

   💡 Tip: For Cloud, you can get the full MCP URL directly from the Console’s Connect modal.

2. Restart Claude Code to pick up the new setting.

1. 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 (format: https://<region-id>.materialize.cloud)	Replace with your value
   Self-Managed	Replace with your value (format: http://<host>:6876)	Replace with your value
   Emulator	http://localhost:6876	Replace with your value

   💡 Tip: For Cloud, you can get the full MCP URL directly from the Console’s Connect modal.

2. Restart Claude Desktop to pick up the new setting.

1. 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 (format: https://<region-id>.materialize.cloud)	Replace with your value
   Self-Managed	Replace with your value (format: http://<host>:6876)	Replace with your value
   Emulator	http://localhost:6876	Replace with your value

   💡 Tip: For Cloud, you can get the full MCP URL directly from the Console’s Connect modal.

2. Restart Cursor to pick up the new setting.

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