NeoZip MCP setup & reference

Installation

Requires Node.js 20+. MCP hosts spawn neozip-mcp from PATH — a project-local npm install is not the supported server install path.

# Once per developer machine (required)
npm install -g neozip-mcp@beta

# Verify binaries are on PATH
which neozip-mcp
which neozip-connect
neozip-connect status

Claude workspace setup

Share NeoZip MCP with your team by committing a project-scoped .mcp.json at the repository root. Anyone who clones the repo and opens it in Claude Code gets the same MCP server definition after approval.

# After global install — copy examples into your repo
pkg="$(npm root -g)/neozip-mcp"
cp "$pkg/docs/examples/mcp.json.claude.example" .mcp.json
cp -R "$pkg/docs/examples/claude/skills" .claude/
# optional: cp "$pkg/docs/examples/CLAUDE.md.example" CLAUDE.md

git add .mcp.json .claude/skills CLAUDE.md
git commit -m "Add NeoZip MCP workspace config for Claude Code"

{
  "mcpServers": {
    "neozip-mcp": {
      "type": "stdio",
      "command": "neozip-mcp",
      "env": {
        "NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
      }
    }
  }
}

# Alternative: Claude Code CLI creates .mcp.json for you
cd /path/to/your/project

claude mcp add-json neozip-mcp \
  '{"type":"stdio","command":"neozip-mcp","env":{"NEOZIP_MCP_SANDBOX_PATHS":"${CLAUDE_PROJECT_DIR:-.},${HOME}"}}' \
  --scope project

Individual Claude Code setup

For solo developers, register NeoZip MCP at user scope so it is available in every project. You still need the global install above.

# User scope — available in every project on your machine
claude mcp add-json neozip-mcp \
  '{"type":"stdio","command":"neozip-mcp","env":{"NEOZIP_MCP_SANDBOX_PATHS":"${CLAUDE_PROJECT_DIR:-.},${HOME}"}}' \
  --scope user

# Copy personal agent skills (once per machine)
pkg="$(npm root -g)/neozip-mcp"
mkdir -p ~/.claude/skills/neozip-mcp ~/.claude/skills/neozip-notarization
cp "$pkg/docs/examples/claude/skills/neozip-mcp/SKILL.md" ~/.claude/skills/neozip-mcp/
cp "$pkg/docs/examples/claude/skills/neozip-notarization/SKILL.md" ~/.claude/skills/neozip-notarization/

Need scriptable automation outside Claude? See NeoZip CLI for JSON I/O and bundled Agent Skills.

Cursor setup

Cursor supports global or per-project mcp.json. The same global neozip-mcp binary requirement applies — install globally, then point Cursor at the command on PATH.

# Cursor — global or per-project mcp.json
# Same global neozip-mcp binary required on PATH

{
  "mcpServers": {
    "neozip-mcp": {
      "command": "neozip-mcp",
      "env": {
        "NEOZIP_MCP_SANDBOX_PATHS": "${workspaceFolder},${userHome}"
      }
    }
  }
}

Copy the excerpt above into ~/.cursor/mcp.json or .cursor/mcp.json in your project. Optional: copy agent skills from the package into ~/.cursor/skills/.

Security

• Path sandboxing — NEOZIP_MCP_SANDBOX_PATHS limits which directories tools may read and write; symlink and traversal protection included.
• Capability scoping — Expose only the tool groups you want (zip, blockchain, readonly, account). Default auto adds blockchain tools after neozip-connect is ready.
• Rate and resource limits — Per-tool throttling, max file size, entry count, and operation timeouts protect against runaway agent loops.
• Local credentials — Account secrets never travel through MCP config; they live under ~/.neozip/connection/ with machine-local encryption. Expired Token Service tokens renew silently via Data Wallet signature when possible.
• Funding gates — fund_wallet request requires NEOZIP_MCP_ALLOW_FUNDING=1 and confirm: true; testnet by default unless NEOZIP_MCP_ALLOW_MAINNET_FUNDING=1.

NeoZip Connect

The neozip-connect companion CLI handles one-time account setup for tokenize, timestamp, recipient encryption, mint, and stamp. Run it once per machine — credentials stay local and are not passed through .mcp.json. After setup, reload your MCP session so blockchain tools appear.

Expired Token Service access tokens renew silently via a Data Wallet signature when possible. For testnet gas, use neozip-connect fund or the gated fund_wallet MCP tool.

# One-time account setup (per machine)
neozip-connect

# Check status anytime
neozip-connect status

# Request a testnet gas grant (human CLI parity with fund_wallet)
neozip-connect fund status
neozip-connect fund

Prefer a GUI-first identity workflow? See NeoZip Desktop and its device-held Data Wallet. CLI users can also use neozip connect.