MCP Configuration¶

Comprehensive configuration options for hanzo-mcp.

Configuration Sources¶

Configuration is loaded in order of precedence (highest first):

CLI arguments
Environment variables
Project config (.hanzo/config.json)
Global config (~/.config/hanzo/mcp-settings.json)
Default settings

CLI Options¶

hanzo-mcp [OPTIONS]

Options:
  --transport [stdio|sse]     Transport mode (default: stdio)
  --host TEXT                 Host for SSE server (default: 127.0.0.1)
  --port INTEGER              Port for SSE server (default: 8888)
  --allow-path PATH           Allowed file system paths (repeatable)
  --project-path PATH         Project paths for context (repeatable)
  --project-dir PATH          Project root directory
  --command-timeout FLOAT     Command timeout in seconds (default: 30)
  --disable-write-tools       Disable file write operations
  --disable-search-tools      Disable search operations
  --install                   Install Claude Desktop configuration
  --dev                       Enable development mode
  --version                   Show version
  --help                      Show help

Environment Variables¶

Core Settings¶

Variable	Default	Description
`HANZO_MCP_TRANSPORT`	`stdio`	Transport mode
`HANZO_MCP_HOST`	`127.0.0.1`	SSE server host
`HANZO_MCP_PORT`	`8888`	SSE server port
`HANZO_AUTO_BACKGROUND_TIMEOUT`	`30`	Command auto-background timeout (seconds)
`HANZO_DEFAULT_SHELL`	`zsh`	Default shell for commands

Agent Settings¶

Variable	Default	Description
`HANZO_AGENT_MODEL`	-	Default model for agent tools
`HANZO_AGENT_API_KEY`	-	API key for agent
`HANZO_AGENT_BASE_URL`	-	Custom API base URL
`HANZO_AGENT_MAX_ITERATIONS`	`10`	Max agent iterations
`HANZO_AGENT_MAX_TOOL_USES`	`30`	Max tool uses per run

LLM API Keys¶

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`TOGETHER_API_KEY`	Together AI API key
`GROQ_API_KEY`	Groq API key

Config File Format¶

Global Config¶

Location: ~/.config/hanzo/mcp-settings.json

{
  "server": {
    "name": "hanzo-mcp",
    "host": "127.0.0.1",
    "port": 8888,
    "transport": "stdio"
  },
  "tools": {
    "command_timeout": 30,
    "disable_write_tools": false,
    "disable_search_tools": false
  },
  "paths": {
    "allowed": ["~"],
    "project": []
  },
  "agent": {
    "enabled": true,
    "model": "claude-3-5-sonnet-20241022",
    "max_iterations": 10,
    "max_tool_uses": 30
  },
  "mcp_servers": []
}

Project Config¶

Location: .hanzo/config.json in project root

{
  "name": "my-project",
  "enabled_tools": {
    "browser": true,
    "database": false
  },
  "disabled_tools": ["vector"],
  "rules": [
    "Use TypeScript for all new files",
    "Follow existing code style"
  ]
}

Tool Configuration¶

Enable/Disable Tools¶

{
  "tools": {
    "enabled": ["shell", "filesystem", "memory", "reasoning"],
    "disabled": ["browser", "database", "vector"]
  }
}

Tool-Specific Settings¶

{
  "tools": {
    "shell": {
      "default_shell": "zsh",
      "timeout": 30
    },
    "browser": {
      "headless": true,
      "default_viewport": "desktop"
    },
    "memory": {
      "scope": "project"
    }
  }
}

Security¶

Path Restrictions¶

By default, the server restricts file access. Use --allow-path to grant access:

# Allow home directory
hanzo-mcp --allow-path ~

# Allow specific project
hanzo-mcp --allow-path /path/to/project

# Allow multiple paths
hanzo-mcp --allow-path ~/work --allow-path /tmp

Disable Dangerous Tools¶

# Read-only mode
hanzo-mcp --disable-write-tools

# No search (for sensitive codebases)
hanzo-mcp --disable-search-tools

Claude Desktop Integration¶

Auto-Install¶

hanzo-mcp --install

This creates the configuration at: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/claude/claude_desktop_config.json

Manual Configuration¶

{
  "mcpServers": {
    "hanzo": {
      "command": "uvx",
      "args": ["hanzo-mcp", "--allow-path", "~"]
    }
  }
}

Debugging¶

Enable Verbose Logging¶

# SSE mode (logging visible)
hanzo-mcp --transport sse

# Check version and config
hanzo-mcp --version

View Running Processes¶

Once connected, use the ps tool:

ps()           # List all background processes
ps(logs="id")  # View process output