Home  /  Manage Materialize  /  Use mz-deploy to manage Materialize

AI agent setup

View as Markdown

mz-deploy was built with AI coding agents in mind. Every new project ships with agent-readable documentation, the CLI provides agent-optimized help, and the language server gives agents real-time feedback on SQL correctness.

Project skill

The community MaterializeInc/agent-skills repo publishes an agent skill for mz-deploy that teaches agents your project’s conventions: one object per file, file paths map to qualified names, how the deployment lifecycle works, unit test syntax, and how to get detailed help with mz-deploy help <command>.

The skill is not installed by default. Install it in your project with:

npx -y skills add MaterializeInc/agent-skills -a universal -a claude-code --project

This drops the skill into .agents/skills/mz-deploy/ and wires up a .claude/skills/ symlink so Claude Code picks it up. Agents that consume the universal skill format (Codex and others) load it from the same location. You don’t need to explain the project’s conventions — the agent already knows them.

Update to the latest version later with:

npx -y skills update

Claude Code on the web

Claude Code on the web runs each session in a fresh, Anthropic-managed cloud sandbox. The sandbox doesn’t have mz-deploy installed, so install it with a setup script — a Bash script that runs once, as root, before Claude Code starts.

In the cloud environment settings, set the Setup script field to:

#!/bin/bash
set -euo pipefail
ARCH=$(uname -m)
curl -L "https://binaries.materialize.com/mz-deploy-latest-$ARCH-unknown-linux-gnu.tar.gz" \
| tar -xzC /usr/local --strip-components=1

The sandbox runs Ubuntu on Linux, so this always uses the unknown-linux-gnu build and resolves the architecture (x86_64 or aarch64) at runtime. The binary lands in /usr/local/bin, which is already on PATH. The script runs as root, so no sudo is needed. Setup scripts have network access under the default Trusted network mode; if your environment uses None, the download will fail.

To configure the language server in the sandbox as well, commit the .claude/settings.json from Configuring for Claude Code to your repository — it carries over to cloud sessions automatically.

Agent-optimized help

mz-deploy help <command>    # Detailed guide for a single command
mz-deploy help --all        # All command guides concatenated

Unlike --help (which prints brief CLI usage), help returns full guides with behavior notes, examples, error recovery steps, and related commands.

Language server

The mz-deploy language server gives agents the same benefits it gives human editors: parse error diagnostics on every file change, go-to-definition across your project, and column-aware completions scoped to actual dependencies.

For agents, this means fewer incorrect SQL suggestions — the agent sees real column names and types from your types.lock rather than guessing.

Configuring for Claude Code

Add to your project’s .claude/settings.json:

{
  "lsp": {
    "mz-deploy": {
      "command": "mz-deploy",
      "args": ["lsp", "-d", "."],
      "filePatterns": ["*.sql"]
    }
  }
}
Back to top ↑