Skip to content

MCPHostConfiguration.md

Latest commit

 

History

History
275 lines (197 loc) · 7.74 KB

MCPHostConfiguration.md

File metadata and controls

275 lines (197 loc) · 7.74 KB

MCP Host Configuration

This article is about:

  • Configuring MCP servers across different host platforms
  • Managing server configurations for Claude, VS Code, Cursor, and other hosts
  • Synchronizing environment configurations to multiple hosts
  • Backup and recovery of host configurations

Overview

Hatch can automatically configure MCP servers on supported host platforms, eliminating the need to manually edit configuration files for each application. This feature streamlines the process of setting up MCP servers across your development environment.

Supported Host Platforms

Hatch currently supports configuration for these MCP host platforms:

  • Claude Desktop - Anthropic's desktop application
  • Claude Code - Anthropic's VS Code extension
  • VS Code - Microsoft Visual Studio Code with MCP extensions
  • Cursor - AI-powered code editor
  • Kiro - Kiro IDE with MCP support
  • Codex - OpenAI Codex with MCP server configuration support
  • LM Studio - Local language model interface
  • Gemini - Google's AI development environment
  • Mistral Vibe - Mistral Vibe CLI coding agent
  • OpenCode - OpenCode AI coding assistant
  • Augment - Augment Code AI assistant

Hands-on Learning

For step-by-step guidance on MCP host configuration, see the comprehensive tutorial series:

Basic Usage

Configure a Server

Add an MCP server to a specific host:

# Configure a local MCP server
hatch mcp configure weather_server \
  --host claude-desktop \
  --command python \
  --args weather_server.py

# Configure a remote MCP server
hatch mcp configure api-service \
  --host cursor \
  --url https://api.example.com/mcp \
  --header "Authorization=Bearer token"

List Configured Servers

View servers configured on a specific host:

# List available host platforms
hatch mcp list hosts

# List configured servers from current environment
hatch mcp list servers

# List servers from specific host
hatch mcp list servers --host claude-desktop

Viewing Host Configurations

Hatch provides multiple ways to view MCP host configurations:

Table Views (for quick overview):

  • hatch mcp list hosts: View all hosts and their servers
  • hatch mcp list servers: View all servers and their hosts

Detailed Views (for comprehensive information):

  • hatch mcp show hosts: Detailed view of all host configurations
  • hatch mcp show servers: Detailed view of all server configurations

Filtering: All commands support regex filtering:

  • hatch mcp list hosts --server "weather.*": Show only servers matching pattern
  • hatch mcp show servers --host "claude.*": Show only hosts matching pattern

Examples:

# View all hosts with their servers (table view)
hatch mcp list hosts

# View all servers with their hosts (table view)
hatch mcp list servers

# View detailed host configurations
hatch mcp show hosts

# View detailed server configurations
hatch mcp show servers

# Filter by server name using regex
hatch mcp show hosts --server "weather.*"

# Filter by host name using regex
hatch mcp show servers --host "claude.*"

Remove a Server

Remove an MCP server from a host:

# Remove server from specific host
hatch mcp remove server weather_server --host claude-desktop

# Remove server from all hosts
hatch mcp remove server weather_server --host all

# Remove entire host configuration
hatch mcp remove host claude-desktop

Configuration Types

Important: Each server must be configured as either local (using --command) or remote (using --url), but not both. These options are mutually exclusive:

  • Local servers: Use --command and optionally --args and --env-var
  • Remote servers: Use --url and optionally --header

Attempting to use both --command and --url will result in an error.

Local Servers

Local servers run as processes on your machine:

# Basic local server
hatch mcp configure my-server \
  --host claude-desktop \
  --command python \
  --args server.py

# Server with environment variables
hatch mcp configure weather_server \
  --host claude-desktop \
  --command python \
  --args weather_server.py \
  --env-var API_KEY=your-key \
  --env-var DEBUG=true

# Server with absolute path (required for some hosts)
hatch mcp configure secure-server \
  --host claude-desktop \
  --command /usr/local/bin/python \
  --args /path/to/secure_server.py

Remote Servers

Remote servers are accessed via HTTP/HTTPS:

# Basic remote server
hatch mcp configure api-server \
  --host cursor \
  --url https://api.example.com/mcp

# Remote server with authentication
hatch mcp configure authenticated-api \
  --host cursor \
  --url https://secure-api.example.com/mcp \
  --header "Authorization=Bearer your-token" \
  --header "Content-Type=application/json"

Multi-Host Configuration

Configure Across Multiple Hosts

Set up the same server on multiple host platforms using the sync command:

# Configure on the primary host first
hatch mcp configure weather_server \
  --host claude-desktop \
  --command python \
  --args weather_server.py

# Then sync to other hosts
hatch mcp sync --from-host claude-desktop --to-host cursor,vscode

# Or sync from an environment to multiple hosts
hatch mcp sync --from-env default --to-host all

Quick Examples

# Sync environment to specific hosts
hatch mcp sync --from-env production --to-host claude-desktop,cursor

# Copy configuration between hosts
hatch mcp sync --from-host claude-desktop --to-host cursor

# Sync with filtering (only servers matching pattern)
hatch mcp sync --from-env dev --to-host all --pattern ".*api.*"

# Preview changes without applying them
hatch mcp sync --from-env prod --to-host all --dry-run

Backup and Recovery

Automatic Backups

Hatch automatically creates backups before modifying host configurations:

# Configure with automatic backup (default)
hatch mcp configure my-server --host claude-desktop --command python --args server.py

# Skip backup creation
hatch mcp configure my-server --host claude-desktop --command python --args server.py --no-backup

Restore From Backups

# List available backups
hatch mcp backup list claude-desktop

# Restore from backup file
hatch mcp backup restore claude-desktop --backup-file <backup_file_name>

Backup Locations

Backups are stored in ~/.hatch/mcp_host_config_backups/ with the naming pattern:

mcp.json.<hostname>.<timestamp>

Host Validation and Error Handling

The system validates host names against available MCP host types:

  • claude-desktop
  • cursor
  • vscode
  • kiro
  • lmstudio
  • gemini
  • Additional hosts as configured

All error messages use standardized formatting with structured details:

[ERROR] Failed to configure MCP server 'my-server'
  Host: claude-desktop
  Reason: Server configuration invalid for claude-desktop

Invalid host names result in clear error messages with available options listed:

[ERROR] Invalid host 'vsc'
  Field: --host
  Suggestion: Supported hosts: claude-desktop, vscode, cursor, kiro, lmstudio, gemini

For complete command syntax and all available options, see CLI Reference.