Aztec MCP Server

An MCP (Model Context Protocol) server that provides local access to Aztec documentation, examples, and source code through cloned repositories. Optionally augments with semantic search over the full Aztec knowledge base when an API key is configured.

Features

• Version Support: Clone specific Aztec release tags (e.g., v4.3.0)
• Local Repository Cloning: Automatically clones Aztec repositories with sparse checkout for efficiency
• Fast Code Search: Search Noir contracts and TypeScript files using ripgrep (with fallback)
• Documentation Search: Search Aztec documentation locally; with an API key, semantic vector search across the full corpora (framework docs, examples, Noir stdlib, TypeScript SDK, protocol circuits)
• Error Lookup: Static catalog (Solidity / circuit / TX / AVM errors) plus optional semantic fallback for unrecognized errors when an API key is configured
• Example Discovery: List and read Aztec contract examples
• Version-sync Gate: When using the hosted semantic backend, the server detects mismatches between your local clone tag and the indexed corpus and refuses to query across versions unless explicitly overridden

API Key (optional, recommended)

The MCP server runs in two modes:

Mode	How to enable	What you get
Local (default)	No setup	Ripgrep search over cloned markdown + code; static error catalog
Semantic (recommended)	Set API_KEY env var	Vector search over all 12 indexed Aztec corpora (developer docs, network docs, Aztec.nr, examples, aztec.js, CLI, TypeScript API, e2e tests, protocol circuits, L1 contracts, Noir docs, Noir stdlib); semantic error fallback; version-sync gate

Getting a key

1. Join the Aztec/Noir Discord: https://discord.gg/xMud5StFyA
2. Run /mcp-key in any channel — the bot DMs you a personal API key (UUID) ephemerally.
3. Paste the key into your MCP client config under env.API_KEY (see Configuration).

Keys are free, persistent (re-running /mcp-key returns the same key), and revocable via /forget-me.

Installation

With npx (recommended)

npx -y @aztec/mcp-server@latest

Always pin @latest. npx caches packages aggressively — without @latest, you can end up running an old version indefinitely. The @latest tag forces npx to check the registry for the current release every run. The server also self-reports an upgrade-available warning at startup if it detects a newer version on npm (see aztec_status output).

Global install

npm install -g @aztec/mcp-server@latest
aztec-mcp

To update later: npm install -g @aztec/mcp-server@latest (or just rely on the npx -y @aztec/mcp-server@latest form, which always fetches current).

Configuration

Claude Code Plugin

Add to your .mcp.json. The minimal config is just the command; add env.API_KEY to enable semantic search.

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "API_KEY": "<your key from /mcp-key in the Noir Discord>"
      }
    }
  }
}

Env var	Default	Purpose
API_KEY	unset	Personal API key from /mcp-key in the Noir Discord (https://discord.gg/xMud5StFyA). Unset → local-only mode.
API_URL	https://aztec.adjacentpossible.dev	DocsGPT backend the semantic search hits. Override to point at a self-hosted instance.
REQUEST_TIMEOUT	60000	Semantic-search request timeout (ms).
AZTEC_DEFAULT_VERSION	v4.3.0	Default version tag for aztec_sync_repos.
AZTEC_MCP_REPOS_DIR	~/.aztec-mcp/repos/	Where local clones live.

Available Tools

aztec_sync_repos

Clone or update Aztec repositories locally. Run this first to enable other tools.

Clones:
- aztec-packages (docs, aztec-nr, noir-contracts) - sparse checkout
- aztec-examples (full)
- aztec-starter (full)

Parameters:

• version (string): Aztec version tag to clone (e.g., v4.3.0). Defaults to latest supported version.
• force (boolean): Force re-clone even if repos exist
• repos (string[]): Specific repos to sync

Example - Clone specific version:

aztec_sync_repos({ version: "v4.3.0" })

aztec_status

Check the status of cloned repositories.

aztec_search_code

Search Aztec contract code and source files. Supports regex patterns.

Parameters:

• query (string, required): Search query (supports regex)
• filePattern (string): File glob pattern (default: *.nr)
• repo (string): Specific repo to search
• maxResults (number): Maximum results (default: 30)

Example:

aztec_search_code({ query: "PrivateSet", filePattern: "*.nr" })

aztec_search_docs

Search Aztec documentation. Local ripgrep by default; semantic vector search when API_KEY is set.

Parameters:

• query (string, required): Documentation search query
• section (string): Docs section, applies to local search only (tutorials, concepts, developers, reference)
• maxResults (number): Maximum results (default: 20 local; 5 semantic, max 20)
• chunks (number, semantic only): Number of result chunks (1-20). If omitted, maxResults is used.
• useLocalFallback (boolean, semantic only): If the semantic backend fails, fall back to local ripgrep. Default false so backend errors surface clearly.
• allowVersionMismatch (boolean, semantic only): Override the version-sync gate. Default false. The gate refuses to search when your local aztec-packages clone tag differs from the corpus version the backend has indexed.

aztec_list_examples

List available Aztec contract examples.

Parameters:

• category (string): Filter by category (token, nft, defi, escrow, crowdfund)

aztec_read_example

Read the source code of an Aztec contract example.

Parameters:

• name (string, required): Example contract name

aztec_read_file

Read any file from cloned repositories.

Parameters:

• path (string, required): File path relative to repos directory

aztec_lookup_error

Diagnose any Aztec error by message, error code, or hex signature. Returns root cause and suggested fix from a static catalog covering Solidity errors, TX validation errors, circuit codes, AVM errors, and operator FAQ. With API_KEY set, falls back to semantic documentation search when the static catalog has no hit.

Parameters:

• query (string, required): Error message, numeric code (e.g., 2002), or hex signature (e.g., 0xa5b2ba17)
• category (string): Filter (contract, circuit, tx-validation, l1, avm, sequencer, operator, general)
• maxResults (number): Default 10
• allowVersionMismatch (boolean, semantic only): Override the version-sync gate for the semantic fallback. Has no effect when the static catalog already matched.

Configuration Options

Storage Location

Repositories are cloned to ~/.aztec-mcp/repos/ by default.

Override with the AZTEC_MCP_REPOS_DIR environment variable:

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "AZTEC_MCP_REPOS_DIR": "/custom/path"
      }
    }
  }
}

Default Aztec Version

Set the default Aztec version with the AZTEC_DEFAULT_VERSION environment variable:

{
  "mcpServers": {
    "aztec-mcp": {
      "command": "npx",
      "args": ["-y", "@aztec/mcp-server@latest"],
      "env": {
        "AZTEC_DEFAULT_VERSION": "v3.0.0-devnet.6-plugin.1"
      }
    }
  }
}

Development

# Clone the repo
git clone https://github.com/aztecprotocol/mcp-server
cd mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

Requirements

• Node.js 18+
• Git
• ripgrep (optional, for faster searching)

Cloned Repositories

Repository	Description	Checkout
aztec-packages	Main monorepo	Sparse: docs, aztec-nr, noir-contracts
aztec-examples	Official examples	Full
aztec-starter	Starter template	Full

License

MIT