mcp/docs/DXT_INSTALLATION.md

Desktop Extensions (DXT) Installation

Hanzo MCP supports installation via Desktop Extensions (.dxt files), providing the easiest way to add Hanzo MCP to Claude Desktop.

What are Desktop Extensions?

Desktop Extensions (DXT) are packaged MCP servers that can be installed with a single click. They include:

• The MCP server code
• All dependencies
• Installation scripts
• Tool definitions and permissions

Installing Hanzo MCP via DXT

Method 1: Download Pre-built DXT

1. Go to the Hanzo MCP Releases page
2. Download the latest hanzo-mcp-*.dxt file
3. Double-click the downloaded file
4. Claude Desktop will automatically install the extension

Method 2: Build Your Own DXT

If you want to build a DXT file from source:

# Clone the repository
git clone https://github.com/hanzoai/mcp
cd mcp

# Install dependencies
make install

# Build the DXT package
make build-dxt

The DXT file will be created in the dist/ directory.

DXT File Structure

A Hanzo MCP DXT file contains:

hanzo-mcp.dxt (ZIP archive)
├── manifest.json          # Extension metadata
├── hanzo_mcp/            # Python package
├── requirements.txt      # Python dependencies  
├── launcher.py          # Entry point script
├── install.sh          # macOS/Linux installer
├── install.bat         # Windows installer
└── README.md           # User documentation

Configuring the Extension

After installation, you can configure Hanzo MCP through Claude Desktop's extension settings:

Allowed Paths

By default, Hanzo MCP can only access your home directory. To allow access to other directories:

1. Open Claude Desktop settings
2. Navigate to Extensions → Hanzo MCP
3. Add allowed paths in the configuration

Feature Flags

You can enable/disable specific features:

• disable_write_tools: Disable all file write operations
• disable_search_tools: Disable search capabilities
• enable_agent_tool: Enable the agent delegation feature

Troubleshooting

Extension Not Loading

1. Check Claude Desktop logs for errors
2. Verify Python 3.10+ is installed on your system
3. Try reinstalling the extension

Permission Denied Errors

1. Ensure the paths you're accessing are in the allowed paths list
2. Check file system permissions
3. On macOS, grant Full Disk Access to Claude Desktop if needed

Missing Tools

Some tools may be disabled by default. Enable them through:

• Extension settings in Claude Desktop
• Using the tool_enable command in Claude

Security Considerations

DXT files declare their required permissions:

• Filesystem: Read/write access to allowed paths
• Network: For agent tools and API integrations
• Execute: For running shell commands

Always review permissions before installing extensions from untrusted sources.

Building Custom DXT Files

To create a custom build with specific configurations:

1. Edit dxt/manifest.json to customize:

   • Tool definitions
   • Default permissions
   • Configuration options

2. Build the package:

   make build-dxt
   

3. The customized DXT file will be in dist/

Distribution

DXT files can be distributed through:

• GitHub Releases
• Direct file sharing
• Desktop Extensions Hub
• Package managers (future)

For Developers

See the DXT Development Guide for detailed information about:

• Creating DXT packages
• Manifest file format
• Build process
• Testing extensions