AI agent setup

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, set up the plugin as described in Configuring for Claude Code and commit your project’s .claude/settings.json 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

Use the mz-sql-lsp plugin, published by the MaterializeInc/agent-skills repo, which also serves as a Claude Code plugin marketplace named materialize. The plugin registers the language server for .sql files and bundles a skill that tells Claude to use LSP navigation instead of grepping when it needs to resolve an object reference, inspect a view’s columns, or find dependents before an edit.

mz-deploy must be on Claude Code’s PATH. Then:

/plugin marketplace add MaterializeInc/agent-skills
/plugin install mz-sql-lsp@materialize

On enable, Claude Code prompts for one required setting, mz-deploy project directory: the directory holding your project.toml, relative to the repository root. Use . when project.toml sits at the root, or a subdirectory name such as mz when the project is nested. The language server takes that directory as its project root. You can change the value later from /plugin, in the plugin’s detail view.