MCP Hub

An aggregating MCP (Model Context Protocol) server that runs multiple child MCP servers as subprocesses and provides a unified interface with automatic process supervision, hot reload, and fault tolerance.

MCP Hub is an aggregating MCP (Model Context Protocol) server that runs multiple child MCP servers as subprocesses and combines their tools into a unified interface for AI editors like Zed.

Features

🚀 Process Supervision - Automatic restart of failed processes with exponential backoff
🔌 Tool Aggregation - Combines tools from multiple MCP servers into one interface
🛡️ Circuit Breaker - Fault tolerance with automatic recovery (3 failures → 30s cooldown)
🏷️ Name Deduplication - Handles tool name conflicts with configurable prefixes
🔧 Tool Filtering - Whitelist/blacklist tools per server
📝 Description Enhancement - Add prefixes/suffixes to tool descriptions
🔄 Hot Reload - Reload configuration without restarting (planned)
⚡ Graceful Shutdown - Clean process termination on SIGINT/SIGTERM

Quick Start

Prerequisites

• Rust 1.75+ with Cargo
• MCP-compatible servers you want to aggregate

Installation

# Clone the repository
git clone https://github.com/your-org/mcp-hub
cd mcp-hub

# Build the project
cargo build --release

# The binary will be available at target/release/mcp-hub

Basic Usage

1. Create a configuration file (see Configuration):

# config.toml
[[server]]
name = "filesystem"
cmd = "python"
args = ["-m", "mcp_filesystem"]
prefix = "fs_"

[[server]]
name = "search"
cmd = "exa_mcp"
prefix = "search_"
[server.env]
EXA_API_KEY = "${EXA_API_KEY}"

2. Run MCP Hub:

./target/release/mcp-hub config.toml

3. Connect your AI editor (like Zed) to MCP Hub via stdio.

Configuration

MCP Hub uses TOML configuration files. Each [[server]] section defines one child MCP server:

Basic Server Configuration

[[server]]
name = "my_server"           # Unique identifier
cmd = "python"               # Command to run
args = ["-m", "my_mcp"]      # Command arguments

Environment Variables

[[server]]
name = "api_server"
cmd = "my-mcp-server"

[server.env]
API_KEY = "${MY_API_KEY}"           # Expands from environment
TIMEOUT = "30"                      # Literal value
USER_HOME = "${HOME:-/tmp}"         # With fallback

Tool Filtering

[[server]]
name = "filtered_server"
cmd = "dangerous-mcp"

# Include only these tools (takes precedence over blacklist)
whitelist = ["safe_tool1", "safe_tool2"]

# OR exclude these tools
blacklist = ["dangerous_tool", "risky_operation"]

Name Deduplication & Description Enhancement

[[server]]
name = "enhanced_server"
cmd = "my-mcp"
prefix = "enhanced_"                           # Prefix for conflicting tool names
description_prefix = "🔧 Enhanced: "          # Prefix for all descriptions
description_suffix = " (via Enhanced API)"    # Suffix for all descriptions

Complete Example

See example.toml for a comprehensive configuration with 10 different server types.

Architecture

Zed Editor ←→ MCP Hub ←→ [exa_mcp, filesystem_mcp, git_mcp, ...]
                │
                ├── Hub Actor (coordinator)
                ├── Process Supervisors (one per child server)
                ├── Circuit Breakers (fault protection)
                └── Configuration Hot Reload

How It Works

1. Startup: MCP Hub spawns all configured child processes
2. Initialization: Gathers tool lists from each server and applies filtering/deduplication
3. Runtime: Routes tool calls to appropriate servers based on tool names
4. Fault Tolerance: Monitors process health, restarts failed processes, and uses circuit breakers
5. Shutdown: Gracefully terminates all child processes on SIGINT/SIGTERM

Process Supervision

• Exponential Backoff: 1s → 2s → 4s → 8s → 15s max delay between restarts
• Retry Limit: Maximum 5 restart attempts before marking as failed
• Isolation: Failed processes don't affect other servers

Circuit Breaker

• Failure Threshold: Opens after 3 consecutive failures
• Recovery Time: Stays open for 30 seconds
• Auto-Recovery: Automatically tries requests after cooldown period

Development

Building from Source

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# With native CPU optimizations
RUSTFLAGS="-C target-cpu=native" cargo build --release

Running Tests

# All tests
cargo test

# Unit tests only
cargo test --lib

# Integration tests only
cargo test --test integration

# With clippy linting
cargo clippy

Debugging

Enable tokio console for runtime inspection:

TOKIO_CONSOLE=1 ./target/debug/mcp-hub config.toml

Then connect with:

tokio-console

Logging

Control log levels with RUST_LOG:

# Default: info for mcp-hub, warn for rmcp
RUST_LOG=debug ./target/release/mcp-hub config.toml

# Detailed logging
RUST_LOG=mcp_hub=trace,rmcp=debug ./target/release/mcp-hub config.toml

Integration with Zed Editor

Add MCP Hub to your Zed settings:

{
  "language_models": {
    "anthropic": {
      "mcp_servers": {
        "mcp-hub": {
          "command": "/path/to/mcp-hub",
          "args": ["/path/to/your/config.toml"]
        }
      }
    }
  }
}

Troubleshooting

Common Issues

Process fails to start:

• Check that the command and arguments are correct
• Verify environment variables are set
• Look at logs for detailed error messages

Tool name conflicts:

• Use prefix in server configuration to disambiguate
• Check logs for deduplication messages

Circuit breaker activated:

• Check if the underlying server is healthy
• Look for patterns in failure logs
• Consider increasing timeout values

Getting Help

• Check the STATUS.md for current development status
• Look at example configurations in example.toml
• Review test cases in tests/ directory for usage patterns

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b my-feature
3. Make changes and add tests
4. Run tests: cargo test
5. Run clippy: cargo clippy
6. Commit changes: git commit -am 'Add my feature'
7. Push to branch: git push origin my-feature
8. Submit a Pull Request

Code Style

• Follow Rust standard formatting: cargo fmt
• Fix all clippy warnings: cargo clippy
• Add tests for new functionality
• Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with rmcp - Rust MCP SDK
• Uses failsafe for circuit breaker pattern
• Inspired by the MCP ecosystem and AI-assisted development workflows