MCP Integration

Per-Tool Setup Guides

Client	Guide
Claude Code	Claude Code Setup
OpenAI Codex	Codex Setup
Google Gemini	Gemini Setup
Cursor	Cursor Setup
Zed	Zed Setup
Neovim	Neovim Setup

Quick Setup

Use az connect to automatically configure MCP for a CLI tool:

az connect claude   # writes .mcp.json for Claude Code
az connect codex    # writes .mcp.json for Codex CLI
az connect gemini   # writes .mcp.json for Gemini CLI

Add --dry-run to preview without writing.

What is MCP?

The Model Context Protocol (MCP) is a standard for AI tools. AgentZero implements an MCP server, letting any MCP-compatible client use its tools with full policy enforcement.

Setup with Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "agentzero": {
      "command": "agentzero",
      "args": ["mcp"]
    }
  }
}

Setup with Cursor

Add to Cursor’s MCP configuration:

{
  "mcpServers": {
    "agentzero": {
      "command": "agentzero",
      "args": ["mcp"]
    }
  }
}

Available Tools

MCP Tool	Description
`read_file`	Read file contents
`list_directory`	List directory contents
`search_files`	Search for patterns in files
`write_file`	Write content to a file
`run_command`	Execute a shell command

Security

All tool calls go through AgentZero’s session engine:

Policy evaluation before every tool execution
Path validation blocks access outside project root
Sensitive paths (.ssh, .env, .aws/credentials) denied
Audit events emitted for every call
Project policy loaded from .agentzero/policy.yml

Protocol Details

AgentZero speaks JSON-RPC 2.0 over stdio:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"agentzero","version":"0.1.0"}}}

→ {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"Cargo.toml"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"[workspace]\n..."}]}}

Building with MCP Support

MCP is behind a feature flag. Build with:

cargo build --features mcp

Running az mcp without the feature compiled in prints a helpful message recommending ACP as the native alternative.

Running Manually

# Start the MCP server (requires --features mcp)
az mcp

# Test with a JSON-RPC request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | az mcp

ACP Alternative

For new integrations, consider using ACP instead. ACP is the native protocol and runs the full agentic loop (LLM inference + tool calling) inside AgentZero, while MCP only exposes individual tools.