@hanzo/mcp

The canonical Model Context Protocol server for the Hanzo AI Cloud — one action-routed tool surface every Hanzo agent runs on.

Quick start

npm install -g @hanzo/mcp
hanzo-mcp serve

What this is

@hanzo/mcp is the canonical MCP server for the Hanzo platform. It collapses a 260+ tool catalog into 13 HIP-0300 action-routed tools (fs, exec, code, git, fetch, workspace, ui, plus optional think, memory, hanzo, plan, tasks, mode) served over the MCP stdio / streamable-http transports.

Every Hanzo agent speaks this same tool surface. The Python SDK (hanzo-mcp on PyPI) and the Rust crate (hanzo-mcp::brain) mirror it 1-to-1, so a tool name and its action schema are identical across all three runtimes.

Implements:

• HIP-0300 — Unified MCP Tools
• HIP-0106 — Unified Cloud Binary (mcp subsystem)

Tool surface (HIP-0300)

13 canonical tools organized by axis. Each tool uses action-routed dispatch — one tool name, many verbs.

Core tools (7)

| Tool | Axis | Key actions | |------|------|-------------| | fs | Bytes + paths | read, write, stat, list, mkdir, rm, mv, apply_patch, search_text | | exec | Execution | run, background, ps, kill, logs | | code | Symbols + semantics | parse, search, transform, summarize | | git | Diffs + history | status, diff, log, commit, branch, stash | | fetch | HTTP | get, post, put, delete, download | | workspace | Project context | info, config, env, dependencies | | ui | UI components | list_components, fetch_component, search, install |

Optional tools (6)

| Tool | Purpose | |------|---------| | think | Structured reasoning | | memory | Persistent storage | | hanzo | Hanzo platform surface (iam, kms, paas, commerce) | | plan | Task planning | | tasks | Task tracking | | mode | Developer modes |

Community tools (opt-in)

Third-party descriptors that shell out to externally-installed binaries. Off by default; enable individually.

| Tool | Source | Purpose | |------|--------|---------| | tesseract.deploy | kcolbchain/tesseract | Deploy zk-OCR relayer to a target chain | | tesseract.health_check | kcolbchain/tesseract | Probe deployed relayer addresses | | tesseract.monitor | kcolbchain/tesseract | Poll matching contract events | | compress.solana | kcolbchain/blockchain-compression | Compress blob with Solana-tuned compressor |

Enable with hanzo-mcp serve --enable-community-cryptuon. See src/tools/community/cryptuon/ for descriptors and per-tool env overrides (e.g. $CRYPTUON_TESSERACT_DEPLOY).

Usage

CLI

# Default: HIP-0300 unified surface (13 tools)
hanzo-mcp serve

# Legacy individual tools (read_file, write_file, bash, …)
hanzo-mcp serve --legacy

# UI extensions
hanzo-mcp serve --enable-ui --enable-desktop

# Disable specific tools
hanzo-mcp serve --disable-tools plan,tasks

# List available tools
hanzo-mcp list-tools

# Install for Claude Desktop
hanzo-mcp install-desktop

Programmatic

import { getConfiguredTools } from '@hanzo/mcp';

// HIP-0300 unified surface (default)
const tools = getConfiguredTools({ unified: true });

// Legacy individual tools
const legacy = getConfiguredTools({ enableLegacy: true });

// With UI extensions
const withUI = getConfiguredTools({
  unified: true,
  enableUI: true,
  enableDesktop: true,
});

Client configuration

Claude Desktop / Cursor / Code

Add to .mcp.json:

{
  "mcpServers": {
    "hanzo": {
      "command": "npx",
      "args": ["-y", "--package=@hanzo/mcp", "hanzo-mcp", "serve"]
    }
  }
}

Why --package=? Without it, npx -y @hanzo/mcp serve resolves serve as a separate npm package (the unrelated static-file server) and runs that instead of hanzo-mcp. The --package= form binds npx to the right binary. This matters on every platform — Windows, macOS, and Linux.

Troubleshooting

If MCP "doesn't work" in Claude Desktop, Claude Code, Cursor, or any other client:

1. Verify the stdio handshake from the command line:

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
     | npx -y --package=@hanzo/mcp@latest hanzo-mcp serve

   A working install prints a JSON-RPC response with "serverInfo":{"name":"hanzo-mcp","version":"…"} within ~10 s. Silence (or a long hang) means the wrong binary is running.

2. Turn on debug logging by setting HANZO_MCP_DEBUG=1 in the client's MCP server env block. Stderr will then include the resolved CLI path, cwd, argv, and PATH prefix — usually enough to tell whether a stray serve binary, a wrong npx arg form, or a port conflict is shadowing the server.

   "hanzo": {
     "command": "npx",
     "args": ["-y", "--package=@hanzo/mcp", "hanzo-mcp", "serve"],
     "env": { "HANZO_MCP_DEBUG": "1" }
   }

   In Claude Desktop the stderr lands in ~/Library/Logs/Claude/mcp-server-hanzo.log (macOS) or %APPDATA%\Claude\logs\mcp-server-hanzo.log (Windows).

3. Rerun the installer to overwrite a stale (2.4.1 or earlier) config:

   npx -y --package=@hanzo/mcp@latest hanzo-mcp install --claude-desktop

   Then restart Claude Desktop.

4. Windows specifics. npx.cmd shells out to cmd.exe for arg parsing, which is sensitive to quoting. If the JSON config uses single quotes anywhere, switch to double quotes.

5. CI invariants. The protocol-level contract is exercised on every push to main, on native Linux amd64 + arm64 (Hanzo self-hosted runners, no QEMU), via scripts/smoke-mcp.mjs and an e2e test against the published npm package using the same npx invocation shipped to clients. If MCP works locally but fails for you, open an issue with the HANZO_MCP_DEBUG=1 log attached.

Architecture

   Claude Desktop / Cursor / Code  ->  stdio MCP transport
                                              |
                                          hanzo-mcp serve
                                              |
                          +-------------------+-------------------+
                          |                                       |
                  HIP-0300 unified tools          legacy individual tools (--legacy)
                  fs / exec / code / git /         read_file, write_file, bash, …
                  fetch / workspace / ui +
                  optional think / memory /
                  hanzo / plan / tasks / mode
                          |
                  TS runtime (today) | Rust runtime (latency-sensitive)
                          |
                  Go runtime under hanzoai/cloud (HIP-0106 in flight)

Source layout:

src/tools/unified/    # HIP-0300 action-routed tools (fs, exec, code, fetch, workspace, hanzo)
src/tools/            # Individual tools (git, think, memory, tasks, plan, mode, …)
rust/src/tools/       # Rust native tools (exec, git, fetch, code, computer, …)

The Rust runtime provides native performance for latency-sensitive operations (<5 ms clicks, <2 ms keypress, <50 ms screenshots).

Python SDK parity

The Python implementation (hanzo-mcp on PyPI) exposes the same 13 HIP-0300 tools via entry-point discovery from hanzo-tools-* packages. Tool names and action schemas are identical across both runtimes.

pip install hanzo-mcp

License

MIT

Hanzo — the Open AI Cloud

Open source · every language · on-chain settlement. hanzo.ai · docs.hanzo.ai

SDKs in every language — Python (flagship) · TypeScript · Go · Rust · C++ · Swift · Kotlin · umbrella