Host Integration

After installing and configuring tools, you need to register them with an MCP host so your AI application can use them. This page explains how to work with different hosts and manage tool registrations.

What Is an MCP Host?

An MCP host is an application that can communicate with MCP servers using the Model Context Protocol. The host acts as the client side of the connection. When you ask the AI to perform a task that requires a tool, the host sends requests to the appropriate MCP server and processes the responses.

The CLI supports eleven hosts:

• Claude Code - Command-line interface for Claude
• OpenCode - Terminal-based AI coding agent
• Codex - OpenAI's CLI agent
• Cursor - AI-powered code editor
• VS Code - Visual Studio Code with the Claude extension
• Claude Desktop - Anthropic's desktop application
• Windsurf - AI-powered development environment
• Zed - High-performance code editor with AI features
• Gemini CLI - Google's command-line AI interface
• Kiro - AWS's AI-powered IDE
• Roo Code - AI coding assistant

Each host has its own configuration file format and storage location. The CLI knows these details and handles them automatically.

Supported Hosts

Claude Code

claude-code

OpenCode

opencode

Codex

codex

Cursor

cursor

VS Code

vscode

Claude Desktop

claude-desktop

Windsurf

windsurf

Zed

zed

Gemini CLI

gemini-cli

Kiro

kiro

Roo Code

roo-code

To see which hosts the CLI supports and their status:

tool host list

This shows each host, whether its configuration file exists, and whether it appears to be installed on your system.

Adding Tools to a Host

The tool host add command registers tools with a host:

tool host add claude-desktop namespace/toolname

This reads the tool's manifest, generates the appropriate configuration, and writes it to the host's configuration file.

You can add multiple tools at once:

tool host add claude-desktop library/bash library/filesystem

To add all installed tools:

tool host add claude-desktop

Without specifying tools, the CLI adds every tool in ~/.tool/tools/.

Host Names and Aliases

Use these names when specifying hosts:

The names are case-insensitive, so Claude-Desktop and CLAUDE-DESKTOP also work.

Short aliases make typing faster:

tool host add cd library/bash     # Same as claude-desktop
tool host add cc library/bash     # Same as claude-code

Previewing Changes

Before modifying the configuration file, you can preview what the CLI will generate:

tool host show claude-desktop library/bash

This prints the configuration that would be added without actually writing it. Useful for understanding what changes will happen or for debugging issues.

Dry Run

The --dry-run flag shows what changes would happen without making them:

tool host add claude-desktop library/bash --dry-run

This is similar to tool host show but in the context of the full add operation.

Handling Existing Entries

If the tool is already registered with the host, the CLI updates the existing entry rather than creating a duplicate. The --overwrite flag ensures that existing configuration gets replaced:

tool host add claude-desktop library/bash --overwrite

Without this flag, the CLI may prompt you to confirm overwriting.

Removing Tools from a Host

To unregister a tool:

tool host remove claude-desktop library/bash

This removes the tool's configuration from the host's file. The tool remains installed; it just will not be available to the AI until you add it again.

You can remove multiple tools:

tool host remove claude-desktop library/bash library/filesystem

Confirmation

The CLI may ask for confirmation before removing. Use -y to skip:

tool host remove claude-desktop library/bash -y

Viewing Host Configuration

To see where a host stores its configuration:

tool host path claude-desktop

This prints the file path. You can then view or edit the file directly if needed.

To see the generated configuration for specific tools:

tool host show claude-desktop library/bash library/filesystem

This shows the JSON that would be written for those tools.

Claude Desktop

Claude Desktop stores MCP configuration in a JSON file. The location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

The configuration file has a mcpServers section where each tool gets an entry:

{
  "mcpServers": {
    "bash": {
      "command": "node",
      "args": ["/path/to/server/index.js"],
      "env": {
        "API_KEY": "configured-value"
      }
    }
  }
}

After adding or removing tools, restart Claude Desktop for changes to take effect. Quit the application completely (not just close the window) and reopen it.

Cursor

Cursor stores MCP configuration in:

• All platforms: ~/.cursor/mcp.json

On Windows, this is %USERPROFILE%\.cursor\mcp.json.

The format is similar to Claude Desktop's format.

After modifying configuration, you may need to reload the MCP extension or restart Cursor.

VS Code

VS Code with MCP support stores configuration in a dedicated file:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json
• Linux: ~/.config/Code/User/mcp.json

The configuration file has a servers section (note: VS Code uses servers instead of mcpServers):

{
  "servers": {
    "bash": {
      "type": "stdio",
      "command": "tool",
      "args": ["run", "--expose", "stdio", "library/bash", "--yes"]
    }
  }
}

Reload the VS Code window after changes for them to take effect.

Claude Code

Claude Code stores configuration in:

• All platforms: ~/.claude.json

On Windows, this is %USERPROFILE%\.claude.json.

The format follows the same pattern as Claude Desktop with a mcpServers section.

Claude Code picks up configuration changes on the next command invocation without needing a restart.

How Configuration Is Generated

When you run tool host add, the CLI:

1. Reads the tool's manifest from ~/.tool/tools/namespace/toolname/manifest.json
2. Reads your configuration from ~/.tool/config/namespace/toolname.json
3. Resolves template variables (like ${user_config.api_key}) to actual values
4. Generates the host-specific configuration format
5. Merges it into the host's configuration file

The generated configuration includes:

• The command to run the server (for stdio transport)
• Command arguments
• Environment variables with configuration values substituted
• For HTTP transport (MCPBX), the URL to connect to

If the tool uses system configuration like an allocated port (MCPBX), the CLI handles that too.

Manual Configuration

Sometimes you need to configure a host manually. You might want to tweak settings the CLI does not expose, or you might be troubleshooting issues.

You can edit the host's configuration file directly. Use tool host path to find it:

tool host path claude-desktop
cat "$(tool host path claude-desktop)"

The file is JSON. Make sure to use valid JSON syntax when editing. Back up the file before making changes.

If you manually edit the configuration, the CLI will still work for adding and removing other tools. It reads the existing file and merges its changes.

Configuration Backups

The CLI creates backups before modifying host configuration files. Backups are stored in ~/.tool/backups/. If something goes wrong, you can restore from a backup.

Troubleshooting

Tool Not Appearing in Host

If you added a tool but the AI cannot see it:

1. Did you restart the host? Most hosts require a restart after configuration changes.
2. Is the tool registered? Run tool host show hostname to see current configuration.
3. Is the configuration file correct? Check tool host path hostname and verify the file contents.
4. Does the tool have required configuration? Missing configuration can prevent the tool from starting.

Host Configuration File Missing

If the CLI says the configuration file does not exist:

1. The host might not be installed
2. The host might not have created its configuration file yet (try opening the host first)
3. The configuration might be in a different location on your system

You can create the file manually if needed. For Claude Desktop, create an empty JSON object:

{
  "mcpServers": {}
}

Tool Starts But Fails

If the tool appears in the host but does not work:

1. Check the tool's logs (hosts usually have a way to view MCP server output)
2. Verify configuration values are correct: tool config get namespace/toolname
3. Test the tool directly: tool call namespace/toolname -m some_method
4. Check that required runtimes (Node.js, Python) are installed

Multiple Hosts

You can register the same tool with multiple hosts. Each host gets its own copy of the configuration. If you change the tool's configuration, you need to update each host:

tool config set namespace/toolname KEY=newvalue
tool host add claude-desktop namespace/toolname --overwrite
tool host add cursor namespace/toolname --overwrite

Or remove and re-add:

tool host remove claude-desktop namespace/toolname
tool host add claude-desktop namespace/toolname