MCP Server for Agents

1. Log in to the Materialize Console.

2. Create a dedicated service account for your specific AI agent (only an Org admin can create service accounts).¹

   For example, to create a new my_agent service account:

   1. Click + Create New and select App Password to open the New app password modal.

   2. In the New app password modal, specify:

      Field	Value
      Type	Service
      Name	MCP
      User	my_agent
      Roles	Organization Member

   3. Click Create Password. The Password and the MCP Token are created.

   4. Save the MCP Token in a secure place. Once you navigate away, the password and the MCP token will not display again. You will use the MCP Token to connect.

      

3. Ensure the corresponding database role has been created, either by:

   • Manually issuing the following commands in the SQL Shell:

     CREATE ROLE my_agent;
     

   • Or, connecting to Materialize (not the MCP server) using the new account. On first connection, Materialize automatically creates the corresponding database role if it does not exist.

4. Grant mcp_agent role to your agent:

   GRANT mcp_agent TO my_agent;
   

5. Set the default cluster and schema for my_agent to mcp_cluster and mcp_schema:

   ALTER ROLE my_agent SET cluster TO mcp_cluster;
   ALTER ROLE my_agent SET search_path TO mcp_schema;
   

   You set these role configurations on the individual roles as configurations are not inherited.

1. Create a login role for your specific AI agent, replacing <your_app_password> with an actual password:

   CREATE ROLE my_agent LOGIN PASSWORD '<your_app_password>';
   

2. Grant mcp_agent role to your agent:

   GRANT mcp_agent TO my_agent;
   

3. Set the default cluster and schema for my_agent to mcp_cluster and mcp_schema:

   ALTER ROLE my_agent SET cluster TO mcp_cluster;
   ALTER ROLE my_agent SET search_path TO mcp_schema;
   

   You set these role configurations on the individual roles as configurations are not inherited.

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

   CREATE ROLE my_agent;
   

2. Grant mcp_agent role to your agent:

   GRANT mcp_agent TO my_agent;
   

3. Set the default cluster and schema for my_agent to mcp_cluster and mcp_schema:

   ALTER ROLE my_agent SET cluster TO mcp_cluster;
   ALTER ROLE my_agent SET search_path TO mcp_schema;
   

   You set these role configurations on the individual roles as configurations are not inherited.

1. Log in to the Materialize Console.

2. Go to App Passwords and for the service account created my_agent, click Connect.

3. Click on the MCP Server tab.

4. In the Get your MCP token section¹,

   • If using my_agent, use the MCP Token that was returned when you created the service account. You can skip to the next step.

   • Otherwise, you can:

     • Create a different service account and use the generated MCP token; or

     • Use an existing service account, Base64 encoding the role:password to generate the MCP token. Ensure the existing account does not have more privileges than necessary.

5. In the Connect your client section, click on the Agent tab.

   You can find your materialize-agent MCP server URL <baseURL>/api/mcp/agent 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. Encode your agent role’s credentials <role>:<password> in Base64 to create the MCP token, replacing <your_app_password> with the actual password:

   printf 'my_agent:<your_app_password>' | base64
   

2. Find your deployment’s host name to determine your materialize-agent MCP URL:

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

   • For your Self-Managed Materialize deployment in AWS/GCP/Azure, the <host> 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 use localhost for <host>:

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

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

   printf 'my_agent:' | base64
   

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

   <baseURL>/api/mcp/agent
   

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

   claude mcp add --transport http "materialize-agent" \
     "<baseURL>/api/mcp/agent" \
     --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-agent 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-agent entry.

   {
     "mcpServers": {
       "materialize-agent": {
         "url": "<baseURL>/api/mcp/agent",
         "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-agent 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-agent": {
         "url": "<baseURL>/api/mcp/agent",
         "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/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <mcp-token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'