io.github.himorishige/hatago-mcp-hub

English | 日本語

🏮 Hatago MCP Hub

Hatago (旅籠) — A relay point connecting modern AI tools with MCP servers.

Overview

Hatago MCP Hub is a lightweight hub that unifies access to multiple MCP (Model Context Protocol) servers from tools like Claude Code, Codex CLI, Cursor, Windsurf, and VS Code.

Documentation

• Docs index: docs/README.md
• Canonical CLI & Hub guide: packages/mcp-hub/README.md
• Public docs site (JA default): https://hatago.dev/ja/ — English: https://hatago.dev/en/

Dev.to: Getting Started with Multi-MCP Using Hatago MCP Hub — One Config to Connect Them All

✨ Features

🚀 Performance (v0.0.14)

• 8.44x Faster Startup - 85.66ms → 10.14ms
• 17% Smaller Package - 1.04MB → 854KB
• Simplified Architecture - Direct server management without abstraction layers

🎯 Simple & Lightweight

• Zero Configuration Start (HTTP mode) - npx @himorishige/hatago-mcp-hub serve --http
• Non-invasive to Existing Projects - Doesn't pollute your project directory

🔌 Rich Connectivity

• Multi-Transport Support - STDIO / HTTP / SSE
• Remote MCP Proxy - Transparent connection to HTTP-based MCP servers
• NPX Server Integration - Dynamic management of npm package MCP servers

🏮 Additional Features

Configuration Updates

• Manual Restart Required - Configuration changes require server restart
• Alternative Solutions:
  • Use process managers (PM2, nodemon) for auto-restart
  • Example: nodemon --exec "hatago serve --http" --watch hatago.config.json
  • Or with PM2: pm2 start "hatago serve" --watch hatago.config.json
• Dynamic Tool List Updates - Supports notifications/tools/list_changed notification

Progress Notification Forwarding

• Child Server Notification Forwarding - Transparent forwarding of notifications/progress
• Long-running Operation Support - Real-time progress updates
• Local/Remote Support - Works with many MCP server types

Built-in Internal Resource

• hatago://servers - JSON snapshot of currently connected servers (id, status, type, tools, resources, prompts)

Enhanced Features

• Environment Variable Expansion - Claude Code compatible ${VAR} and ${VAR:-default} syntax
• Configuration Validation - Type-safe configuration with Zod schemas
• Tag-based Server Filtering - Group and filter servers using tags
• Configuration Inheritance - Extend base configurations with extends field for DRY principle

Minimal Hub Interface (IHub)

External packages (server/test-utils) use a thin IHub interface to avoid tight coupling with the concrete class.

import type { IHub } from '@himorishige/hatago-hub';
import { createHub } from '@himorishige/hatago-hub/node';

const hub: IHub = createHub({
  preloadedConfig: { data: { version: 1, mcpServers: {} } }
}) as IHub;
await hub.start();
hub.on('tool:called', (evt) => {
  /* metrics, logs */
});
await hub.stop();

Extracted modules for thin hub:

• RPC handlers: packages/hub/src/rpc/handlers.ts
• HTTP handler: packages/hub/src/http/handler.ts

📁 Project Structure

packages/
├── mcp-hub/        # Main npm package (@himorishige/hatago-mcp-hub)
├── server/         # Server implementation (@himorishige/hatago-server)
├── hub/            # Hub core (@himorishige/hatago-hub)
├── core/           # Shared types (@himorishige/hatago-core)
├── runtime/        # Runtime components (@himorishige/hatago-runtime)
├── transport/      # Transport layer (@himorishige/hatago-transport)
├── cli/            # CLI tools (@himorishige/hatago-cli)
├── hub-management/ # Management components (@himorishige/hatago-hub-management)
└── test-fixtures/  # Test utilities

📦 Installation

Quick Start (No Installation)

# Initialize configuration
npx @himorishige/hatago-mcp-hub init

# Start in STDIO mode (for Claude Code)
# NOTE: STDIO requires a config file path
npx @himorishige/hatago-mcp-hub serve --stdio --config ./hatago.config.json

# Or start in HTTP mode without a config (demo/dev)
npx @himorishige/hatago-mcp-hub serve --http

Global Installation

# Install globally
npm install -g @himorishige/hatago-mcp-hub

# Use with hatago command
hatago init
hatago serve

As Project Dependency

# Install as dependency
npm install @himorishige/hatago-mcp-hub

# Add to package.json scripts
{
  "scripts": {
    "mcp": "hatago serve"
  }
}

🚀 Usage

Claude Code, Codex CLI, Gemini CLI

STDIO Mode (Recommended)

Claude Code / Gemini CLI

Add to .mcp.json:

{
  "mcpServers": {
    "hatago": {
      "command": "npx",
      "args": [
        "@himorishige/hatago-mcp-hub",
        "serve",
        "--stdio",
        "--config",
        "./hatago.config.json"
      ]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.hatago]
command = "npx"
args = ["-y", "@himorishige/hatago-mcp-hub", "serve", "--stdio", "--config", "./hatago.config.json"]

HTTP Mode

Claude Code / Gemini CLI

Add to .mcp.json:

{
  "mcpServers": {
    "hatago": {
      "url": "http://localhost:3535/mcp"
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.hatago]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:3535/mcp"]

MCP Inspector

For testing and debugging:

# Start in HTTP mode
hatago serve --http --port 3535

# Connect with MCP Inspector
# Endpoint: http://localhost:3535/mcp

Visit MCP Inspector

Metrics (opt-in)

Enable lightweight in-memory metrics and expose an HTTP endpoint:

HATAGO_METRICS=1 hatago serve --http --port 3535
# Then visit: http://localhost:3535/metrics

Notes:

• Metrics are disabled by default and add near-zero overhead when off.
• JSON logs are available when HATAGO_LOG=json (respecting HATAGO_LOG_LEVEL).

⚙️ Configuration

Basic Configuration

Create hatago.config.json:

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-mcp-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Remote Server Configuration

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse",
      "type": "sse"
    },
    "custom-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Configuration Strategies

Strategy 1: Tag-based Filtering

Group servers with tags in a single configuration file:

{
  "mcpServers": {
    "filesystem-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["dev", "local"]
    },
    "github-prod": {
      "url": "https://api.github.com/mcp",
      "type": "http",
      "tags": ["production", "github"]
    },
    "database": {
      "command": "mcp-server-postgres",
      "tags": ["dev", "production", "database"]
    }
  }
}

Start with specific tags:

# Only start servers tagged as "dev"
hatago serve --tags dev

# Start servers with either "dev" or "test" tags
hatago serve --tags dev,test

# Japanese tags are supported
hatago serve --tags 開発,テスト

Strategy 2: Configuration Inheritance

Split configurations by environment using the extends field:

Base configuration (~/.hatago/base.config.json):

{
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

Work configuration (./work.config.json):

{
  "extends": "~/.hatago/base.config.json",
  "logLevel": "debug",
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${WORK_GITHUB_TOKEN}",
        "DEBUG": null
      }
    },
    "internal-tools": {
      "url": "https://internal.company.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

Features:

• Inheritance: Child configs override parent values
• Multiple parents: "extends": ["./base1.json", "./base2.json"]
• Path resolution: Supports ~, relative, and absolute paths
• Environment deletion: Use null to remove inherited env vars

Choosing a Strategy

Environment Variable Expansion

Supports Claude Code compatible syntax:

• ${VAR} - Expands to the value of VAR (error if undefined)
• ${VAR:-default} - Uses default value if VAR is undefined

📋 Commands

hatago init

Create configuration file with interactive setup:

hatago init                    # Interactive mode
hatago init --mode stdio       # STDIO mode config
hatago init --mode http        # HTTP mode config
hatago init --force            # Overwrite existing

hatago serve

Start MCP Hub server:

hatago serve --stdio --config ./hatago.config.json  # STDIO mode (default, requires config)
hatago serve --http                                     # HTTP mode (config optional)
hatago serve --config custom.json  # Custom config
hatago serve --verbose         # Debug logging
hatago serve --tags dev,test   # Filter servers by tags
hatago serve --env-file ./.env # Load variables from .env before start (repeatable)
hatago serve --env-override    # Override existing env vars when using --env-file

Loading Environment Variables from Files

Use --env-file <path...> to load variables before config parsing. This helps resolve ${VAR} and ${VAR:-default} placeholders without exporting variables globally.

• Format: KEY=VALUE, export KEY=VALUE, # comments, blank lines.
• Quotes are stripped; supports escaped \n, \r, \t.
• Paths: relative to CWD, ~/ expanded to home.
• Precedence: files are applied in the given order; existing process.env keys are preserved unless --env-override is provided.

✨ Performance Improvements (v0.0.14)

• 8.44x faster startup: 85.66ms → 10.14ms
• 17% smaller package: 1.04MB → 854KB (181KB reduction)
• Simplified architecture: Removed EnhancedHub and management layers
• Trade-off: Built-in config watching removed (use nodemon/PM2 instead)

🔧 Advanced Usage

Programmatic API

import { startServer } from '@himorishige/hatago-mcp-hub';

// Start server programmatically
await startServer({
  mode: 'stdio',
  config: './hatago.config.json',
  logLevel: 'info'
});

Creating Custom Hub

import { createHub } from '@himorishige/hatago-mcp-hub';

const hub = createHub({
  mcpServers: {
    memory: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-memory']
    }
  }
});

// Use hub directly in your application
const tools = await hub.listTools();

🏗️ Architecture

Client (Claude Code, etc.)
    ↓
Hatago Hub (Router + Registry)
    ↓
MCP Servers (Local, NPX, Remote)

Supported MCP Servers

Local Servers

• Any executable MCP server
• Python, Node.js, or binary servers
• Custom scripts with MCP protocol

NPX Servers

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-github
• @modelcontextprotocol/server-memory
• Any npm-published MCP server

Remote Servers

• DeepWiki MCP (https://mcp.deepwiki.com/sse)
• Any HTTP-based MCP endpoint
• Custom API servers with MCP protocol

🐛 Troubleshooting

Common Issues

1. "No onNotification handler set" warning
   • Normal in HTTP mode with StreamableHTTP transport
   • Hub handles notifications appropriately
2. Server connection failures
   • Verify environment variables are set
   • Check remote server URLs are accessible
   • Use --verbose flag for detailed logs
3. Tool name collisions
   • Hatago automatically prefixes with server ID
   • Original names preserved in hub

Debug Mode

# Enable verbose logging
hatago serve --verbose

# Check server status
hatago status

📚 Documentation

• Configuration Guide
• Architecture Overview
• API Reference
• Team Development Use Cases

🤝 Contributing

Contributions are welcome! Please see our GitHub repository for more information.

📄 License

MIT License

🔗 Links

• npm Package
• GitHub Repository
• MCP Protocol Specification

🙏 Credits

Built with the Hono and the Model Context Protocol SDK by Anthropic.