Basic Configuration

Create a config

Interactive (recommended)

npx @himorishige/hatago-mcp-hub init

The wizard generates a sensible starter config.

Manual

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {}
}

Structure

{
  "$schema": "...",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "server-id": {
      // server definition
    }
  }
}

Tip

With $schema editors like VS Code provide completions and validation.

Server types

Local

{
  "mcpServers": {
    "local-fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": { "LOG_LEVEL": "debug" },
      "cwd": "."
    }
  }
}

Remote (HTTP/SSE)

{
  "mcpServers": {
    "api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    },
    "stream": {
      "url": "https://stream.example.com/mcp",
      "type": "sse"
    }
  }
}

Environment variables

• ${VAR} — expands to variable (errors if undefined)
• ${VAR:-default} — uses default when undefined

Example:

{
  "env": {
    "API_URL": "${API_URL:-https://api.example.com}",
    "LOG_LEVEL": "${LOG_LEVEL:-info}",
    "TIMEOUT": "${TIMEOUT_MS:-30000}"
  }
}

Tag-based management

{
  "mcpServers": {
    "dev-tools": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["development", "local"]
    },
    "prod-api": {
      "url": "https://api.production.com/mcp",
      "tags": ["production", "remote"]
    },
    "shared-db": {
      "command": "mcp-postgres",
      "tags": ["development", "production", "database"]
    }
  }
}

Start with tags:

hatago serve --tags development
hatago serve --tags development,local

Best practices

1. Use clear IDs

   ✅ "github-api", "local-filesystem" / ❌ "srv1"

2. Provide defaults for env vars

   { "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost/dev}" }

3. Organize with tags (environment, purpose, criticality)
4. Disable unused servers with "disabled": true
5. Adjust log level per environment via env

Validate & test

# JSON syntax
cat hatago.config.json | jq .

# Run with verbose logs (Ctrl+C to stop)
hatago serve --stdio --config ./hatago.config.json --verbose

Hot reload

hatago serve --watch

On change: reload config, reconnect servers, notify clients.

Related

Config Inheritance

Remote Servers

Tag Filtering

Config Reference