MCP Aggregator

English | Русский

An MCP server aggregator that reads configuration from MCP.json, automatically spawns child MCP servers, and proxies their tools, resources, and prompts through a single unified interface for LLMs.

Features

🚀 Auto-launch child MCP servers from a single configuration file
🔄 Auto-restart on crash (exponential backoff, up to 5 attempts)
🛠 Tools — proxied with {serverName}-{toolName} prefixes
📄 Resources — proxied via agg://{serverName}/{originalUri} URIs
💬 Prompts — proxied with {serverName}-{promptName} prefixes
🪶 Non-invasive — child servers remain unaware of the aggregator
📝 stderr logging — stdout is reserved for the MCP protocol
🛡️ Fault-tolerant — a failing server doesn't break the rest

Installation

Global via npm

npm install -g @vugu/mcp-aggregator

On-demand via npx

npx @vugu/mcp-aggregator --config MCP.json

From source

git clone https://github.com/vuguzum/mcp-aggregator.git
cd mcp-aggregator
npm install

Quick Start

Create an MCP.json file describing your MCP servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./memory.jsonl"
      }
    }
  }
}

Run the aggregator:

npx @vugu/mcp-aggregator --config MCP.json

Usage

# With default config (MCP.json in current directory)
mcp-aggregator

# With a custom config path
mcp-aggregator --config /path/to/mcp.json

# With debug logging enabled
DEBUG=1 mcp-aggregator --config MCP.json

Connecting to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aggregator": {
      "command": "npx",
      "args": ["-y", "@vugu/mcp-aggregator", "--config", "/path/to/MCP.json"]
    }
  }
}

Or use a local installation:

{
  "mcpServers": {
    "aggregator": {
      "command": "node",
      "args": ["/path/to/mcp-aggregator/src/index.js", "--config", "/path/to/MCP.json"]
    }
  }
}

Configuration Format (MCP.json)

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

Each server is described by:

command (required) — the command used to launch
args (optional) — array of command-line arguments
env (optional) — extra environment variables

Tool Naming Convention

Tools are prefixed with the server name to ensure uniqueness:

| Server | Original Name | Aggregated Name | |--------|---------------|-----------------| | filesystem | read_file | filesystem-read_file | | web-search | search | web-search-search | | memory | create_entities | memory-create_entities | | sequential-thinking | sequentialthinking | sequential-thinking-sequentialthinking |

Each tool's description is also prefixed with [serverName] for clarity.

Environment Variables

| Variable | Description | |----------|-------------| | MCP_CONFIG | Path to the config file (if --config is not provided) | | DEBUG=1 | Enable verbose debug logging |

Project Structure

mcp-aggregator/
├── package.json          # dependencies and scripts
├── MCP.json              # child server configuration
├── MCP.json.example      # example configuration
├── README.md             # this documentation (English)
├── README.ru.md          # Russian documentation
├── LICENSE
├── .gitignore
└── src/
    ├── index.js          # entry point, startup, stdio transport
    ├── aggregator.js     # main aggregator, MCP request handlers
    ├── child-server.js   # child MCP server wrapper
    ├── config.js         # config loading and validation
    └── logger.js         # stderr logger

Debugging

Use the MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js --config MCP.json

Or enable debug mode:

DEBUG=1 mcp-aggregator --config MCP.json

Fault Tolerance

If a child server fails to start, the aggregator continues with the remaining ones
Lost connections are automatically re-established with exponential backoff (up to 5 retries)
Tool errors are returned as isError: true without crashing the aggregator
Graceful shutdown on SIGINT / SIGTERM / stdin close

How It Works

Load configuration — reads MCP.json and parses mcpServers
Spawn child servers — launches each server as a subprocess via StdioClientTransport (acting as an MCP client)
Discover capabilities — calls listTools, listResources, and listPrompts on each server
Proxy requests — registers aggregator-level handlers and routes calls to the appropriate child server, adding prefixes to names

Publishing to npm

# Login to npm (if not already logged in)
npm login

# Publish the package (scoped packages are public by default via publishConfig)
npm publish

After publishing, the package will be available at npmjs.com/package/@vugu/mcp-aggregator.

MCP Servers