@hanzo/mcp

An MCP server for coding agents: files, shell, code, git, HTTP, project context and UI components, plus tools that call the Hanzo API. It speaks MCP over stdio, or over streamable HTTP with --transport http.

Register it with an agent

The package declares Node 18 or newer. For Claude Code:

claude mcp add hanzo -- npx -y @hanzo/mcp serve

npx -y @hanzo/mcp install --claude-code runs that command with --scope user, which registers the server for every project.

claude mcp list then reports hanzo: npx -y @hanzo/mcp serve - ✔ Connected. With --scope project the entry goes into the project's .mcp.json instead, and Claude Code asks before it starts a server from that file. Other MCP clients take the same command in their server config:

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

The first start downloads the package; with an empty npm cache that took 80 to 100 seconds.

Tools

serve with no flags offers these, in the groups src/tools/unified/index.ts defines:

group	tools
core	fs, exec, code, git, fetch, workspace, ui
optional	think, memory, hanzo, plan, tasks, mode, gimp
code intelligence	code_search, code_context, code_ask, code_index
tracker	tracker_boards, tracker_issues, tracker_create, tracker_update
kai	kai_decide, kai_choice, kai_score, kai_noul, kai_tool_select, kai_next_action, kai_command_guard, kai_injection_screen, kai_extract, kai_log_triage, kai_recover, kai_agent_step

The core and optional tools take an action argument that picks the operation; ui takes method. The code intelligence, tracker and kai tools call https://api.hanzo.ai with the key in HANZO_API_KEY, or a local Kai instance via LOCAL_KAI_URL (a local kai serve, e.g. http://127.0.0.1:8080).

The kai tools ask Kai, Hanzo's decision model, typed questions about a case (POST /v1/decisions) and answer with calibrated probabilities: kai_choice picks a label, kai_score an ordinal level, kai_noul the probability that a statement holds, and kai_decide asks up to 100 of them in one call.

Beside the decision primitives: kai_injection_screen (rules and Kai's planted capability, kai-1.3), kai_command_guard (allow, ask or deny before a command runs), kai_tool_select (named tool, then BM25), kai_log_triage (failure signatures), kai_recover (loop breaker and a step for each failure class), kai_next_action (precondition filter, then BM25) and kai_extract (typed fields, abstaining near uniform). Only the screen, kai_extract and kai_decide call Kai; the others decide by rules because kai-1.2 measured at or near chance there. The cookbook has the held-out reads and fifteen runnable recipes. instructions is optional on every question and recommended. A kai_choice call:

{ "state": "I was charged twice for my March invoice. Please refund the duplicate.",
  "instructions": "Which team should handle this ticket?",
  "criteria": { "billing": "charges, invoices and refunds", "product": "how to use the product" } }

hanzo reaches every Hanzo Cloud subsystem: resource names one, action one of its operations, args that operation's arguments. With no action it lists the resource's operations, and resource: "describe" with args: {subsystem, op} says what one takes. The list is generated from cloud's catalog.

{ "resource": "graph", "action": "graphResolve",
  "args": { "entity": "acme/svc/api", "relation": "owner", "as_of": "2026-09-01T00:00:00Z" } }

Flags on serve change the set:

flag	effect
--disable-tools plan,tasks	removes the named tools
--core-only	only the core group
--enable-ui	adds the ui_* component tools
--enable-desktop	adds hanzo_desktop and playwright_control
--enable-autogui, --enable-orchestration, --enable-ui-registry, --enable-github-ui, --enable-community-cryptuon	add those tool sets
--full-surface	adds the UI, AutoGUI, orchestration, UI registry and GitHub UI sets together

npx -y @hanzo/mcp serve --help lists every flag. This prints the tool names a server offers; put any flags after serve:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| npx -y @hanzo/mcp serve 2>/dev/null \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const l of s.split("\n"))if(l.includes("\"id\":2"))console.log(JSON.parse(l).result.tools.map(t=>t.name).join(" "))})'

Over HTTP

npx -y @hanzo/mcp serve --transport http --port 3000

The endpoint is the root path, http://127.0.0.1:3000/. POST JSON-RPC to it with Accept: application/json, text/event-stream; answers come back as server-sent events.

When a client shows no tools

Start the server by hand. A working one answers initialize with its name and version:

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

With HANZO_MCP_DEBUG=1 in the server's environment, stderr also shows its working directory, the resolved binary, its arguments and the start of PATH.

Python

hanzo-mcp on PyPI is a separate server, built from hanzoai/python-sdk.

Development

pnpm install
pnpm build
pnpm smoke    # runs dist/cli.js over stdio: initialize, tools/call, resources

License

MIT