# Mcp Hub

> A centralized manager for Model Context Protocol (MCP) servers with dynamic server management and monitoring

- **Type:** MCP server
- **Install:** `agentstack add mcp-ravitemer-mcp-hub`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ravitemer](https://agentstack.voostack.com/s/ravitemer)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ravitemer](https://github.com/ravitemer)
- **Source:** https://github.com/ravitemer/mcp-hub
- **Website:** https://www.npmjs.com/package/mcp-hub

## Install

```sh
agentstack add mcp-ravitemer-mcp-hub
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Hub 

[](https://www.npmjs.com/package/mcp-hub)
[](https://opensource.org/licenses/MIT)
[](./CONTRIBUTING.md)

MCP Hub acts as a central coordinator for MCP servers and clients, providing two key interfaces:

1. **Management Interface** (/api/*): Manage multiple MCP servers through a unified REST API and web UI
2. **MCP Server Interface** (/mcp): Connect ANY MCP client to access ALL server capabilities through a single endpoint

This dual-interface approach means you can manage servers through the Hub's UI while MCP clients (Claude Desktop, Cline, etc.) only need to connect to one endpoint (`localhost:37373/mcp`) to access all capabilities. Implements [MCP 2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) specification.

## Feature Support

| Category | Feature | Support | Notes |
|----------|---------|---------|-------|
| **Transport** ||||
| | streamable-http | ✅ | Primary transport protocol for remote servers |
| | SSE | ✅ | Fallback transport for remote servers |
| | STDIO | ✅ | For running local servers |
| **Authentication** ||||
| | OAuth 2.0 | ✅ | With PKCE flow |
| | Headers | ✅ | For API keys/tokens |
| **Capabilities** ||||
| | Tools | ✅ | List tools |
| | 🔔 Tool List Changed | ✅ | Real-time updates |
| | Resources | ✅ | Full support |
| | 🔔 Resource List Changed | ✅ | Real-time updates |
| | Resource Templates | ✅ | URI templates |
| | Prompts | ✅ | Full support |
| | 🔔 Prompts List Changed | ✅ | Real-time updates |
| | Roots | ❌ | Not supported |
| | Sampling | ❌ | Not supported |
| | Completion | ❌ | Not supported |
| **Marketplace** ||||
| | Server Discovery | ✅ | Browse available servers |
| | Installation | ✅ | Auto configuration |
| **Real-time** ||||
| | Status Updates | ✅ | Server & connection state |
| | Capability Updates | ✅ | Automatic refresh |
| | Event Streaming to clients | ✅ | SSE-based |
| | Auto Reconnection | ✅ | With backoff |
| **Development** ||||
| | Hot Reload | ✅ | Auto restart a MCP server on file changes with `dev` mode |
| **Configuration** ||||
| | `${}` Syntax | ✅ | Environment variables and command execution across all fields |
| | VS Code Compatibility | ✅ | Support for `servers` key, `${env:}`, `${input:}`, predefined variables |
| | JSON5 Support | ✅ | Comments and trailing commas in configuration files |

## Simplified Client Configuration

Configure all MCP clients with just one endpoint:
```json
{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}
```

The Hub automatically:
- Namespaces capabilities to prevent conflicts (e.g., `filesystem__search` vs `database__search`)
- Routes requests to the appropriate server
- Updates capabilities in real-time when servers are added/removed
- Handles authentication and connection management

## Key Features

- **Unified MCP Server Endpoint** (/mcp):
  - Single endpoint for ALL MCP clients to connect to
  - Access capabilities from all managed servers through one connection
  - Automatic namespacing prevents conflicts between servers
  - Real-time capability updates when servers change
  - Simplified client configuration - just one endpoint instead of many

- **Dynamic Server Management**:
  - Start, stop, enable/disable servers on demand
  - Real-time configuration updates with automatic server reconnection
  - Support for local (STDIO) and remote (streamable-http/SSE) MCP servers 
  - Health monitoring and automatic recovery
  - OAuth authentication with PKCE flow
  - Header-based token authentication

- **Unified REST API**:
  - Execute tools from any connected server
  - Access resources and resource templates
  - Real-time status updates via Server-Sent Events (SSE)
  - Full CRUD operations for server management

- **Real-time Events & Monitoring**:
  - Live server status and capability updates
  - Client connection tracking
  - Tool and resource list change notifications
  - Structured JSON logging with file output

- **Client Connection Management**:
  - Simple SSE-based client connections via /api/events
  - Automatic connection cleanup on disconnect
  - Optional auto-shutdown when no clients connected
  - Real-time connection state monitoring

- **Process Lifecycle Management**:
  - Graceful startup and shutdown handling
  - Proper cleanup of server connections
  - Error recovery and reconnection

- **Workspace Management**:
  - Track active MCP Hub instances across different working directories
  - Global workspace cache in XDG-compliant state directory
  - Real-time workspace updates via SSE events
  - API endpoints to list and monitor active workspaces

### Components

#### Hub Server
The main management server that:
- Maintains connections to multiple MCP servers
- Provides unified API access to server capabilities
- Handles server lifecycle and health monitoring
- Manages SSE client connections and events
- Processes configuration updates and server reconnection

#### MCP Servers
Connected services that:
- Provide tools, resources, templates, and prompts
- Support two connectivity modes:
  - Script-based STDIO servers for local operations
  - Remote servers (streamable-http/SSE) with OAuth support
- Implement real-time capability updates
- Support automatic status recovery
- Maintain consistent interface across transport types

## Installation

```bash
npm install -g mcp-hub
```

## Basic Usage

Start the hub server:

```bash
mcp-hub --port 3000 --config path/to/config.json

# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
```

### CLI Options
```bash
Options:
  --port            Port to run the server on (required)
  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help       Show help information
```

## Configuration

MCP Hub uses JSON configuration files to define managed servers with **universal `${}` placeholder syntax** for environment variables and command execution.

## VS Code Configuration Compatibility

MCP Hub provides seamless compatibility with VS Code's `.vscode/mcp.json` configuration format, enabling you to use the same configuration files across both VS Code and MCP Hub.

### Supported Features

#### Server Configuration Keys
Both `mcpServers` and `servers` keys are supported:

```json
{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}
```

#### Variable Substitution
MCP Hub supports VS Code-style variable substitution:

- **Environment Variables**: `${env:VARIABLE_NAME}` or `${VARIABLE_NAME}`
- **Workspace Variables**: `${workspaceFolder}`, `${userHome}`, `${pathSeparator}`
- **Command Execution**: `${cmd: command args}`

**Supported Predefined Variables:**
- `${workspaceFolder}` - Directory where mcp-hub is running
- `${userHome}` - User's home directory  
- `${pathSeparator}` - OS path separator (/ or \)
- `${workspaceFolderBasename}` - Just the folder name
- `${cwd}` - Alias for workspaceFolder
- `${/}` - VS Code shorthand for pathSeparator

#### VS Code Input Variables
For `${input:}` variables used in VS Code configs, use the `MCP_HUB_ENV` environment variable:

```bash
# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# Then use in config
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}
```

### Migration from VS Code
Existing `.vscode/mcp.json` files work directly with MCP Hub. Simply point MCP Hub to your VS Code configuration:

```bash
mcp-hub --config .vscode/mcp.json --port 3000
```

### Multiple Configuration Files

MCP Hub supports loading multiple configuration files that are merged in order. This enables flexible configuration management:

- **Global Configuration**: System-wide settings (e.g., `~/.config/mcphub/global.json`)
- **Project Configuration**: Project-specific settings (e.g., `./.mcphub/project.json`)
- **Environment Configuration**: Environment-specific overrides

When multiple config files are specified, they are merged with later files overriding earlier ones:

```bash
# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
```

**Merge Behavior:**
- `mcpServers` sections are merged (server definitions from later files override earlier ones)
- Other top-level properties are completely replaced by later files
- Missing config files are silently skipped

### Universal Placeholder Syntax

- **`${ENV_VAR}`** or **`${env:ENV_VAR}`** - Resolves environment variables
- **`${cmd: command args}`** - Executes commands and uses output
- **`${workspaceFolder}`** - Directory where mcp-hub is running
- **`${userHome}`** - User's home directory
- **`${pathSeparator}`** - OS path separator
- **`${input:variable-id}`** - Resolves from MCP_HUB_ENV (VS Code compatibility)
- **`null` or `""`** - Falls back to `process.env`

### Configuration Examples

#### Local STDIO Server
```json
{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}
```

#### Remote Server
```json
{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}
```

### Configuration Options

MCP Hub supports both STDIO servers and remote servers (streamable-http/SSE). The server type is automatically detected from the configuration. **All fields support the universal `${}` placeholder syntax.**

#### STDIO Server Options

For running script-based MCP servers locally:

- **command**: Command to start the MCP server executable (supports `${VARIABLE}` and `${cmd: command}`)
- **args**: Array of command line arguments (supports `${VARIABLE}` and `${cmd: command}` placeholders)
- **env**: Environment variables with placeholder resolution and system fallback
- **cwd**: The cwd for process spawning the MCP server
- **dev**: Development mode configuration (optional)
  - **enabled**: Enable/disable dev mode (default: true)
  - **watch**: Array of glob patterns to watch for changes (default: ["**/*.js", "**/*.ts", "**/*.json"])
  - **cwd**: **Required** absolute path to the server's working directory for file watching

##### Global Environment Variables (`MCP_HUB_ENV`)

MCP Hub will look for the environment variable `MCP_HUB_ENV` (a JSON string) in its own process environment. If set, all key-value pairs from this variable will be injected into the environment of every managed MCP server (both stdio and remote). This is useful for passing secrets, tokens, or other shared configuration to all servers without repeating them in each server config.

- Server-specific `env` fields always override values from `MCP_HUB_ENV`.
- Example usage:
  ```sh
  MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json
  ```

#### Remote Server Options

For connecting to remote MCP servers:

- **url**: Server endpoint URL (supports `${VARIABLE}` and `${cmd: command}` placeholders)
- **headers**: Authentication headers (supports `${VARIABLE}` and `${cmd: command}` placeholders)

#### Server Type Detection

The server type is determined by:
- STDIO server → Has `command` field
- Remote server → Has `url` field

Note: A server configuration cannot mix STDIO and remote server fields.

#### Placeholder Resolution Order

1. **Commands First**: `${cmd: command args}` are executed first
2. **Environment Variables**: `${VAR}` are resolved from `env` object, then `process.env`
3. **Fallback**: `null` or `""` values fall back to `process.env`
4. **Multi-pass**: Dependencies between variables are resolved automatically

## Nix

### Nixpkgs install

> coming...

### Flake install

Just add it to your NixOS flake.nix or home-manager:

```nix
inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}
```

To integrate mcp-hub to your NixOS/Home Manager configuration, add the following to your environment.systemPackages or home.packages respectively:

```nix
inputs.mcp-hub.packages."${system}".default
```

### Usage without install

If you want to use mcphub.nvim without having mcp-hub server in your PATH you can link the server under the hood adding
the mcp-hub nix store path to the `cmd` command in the plugin config like

[Nixvim](https://github.com/nix-community/nixvim) example:
```nix
{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}
```

## Example Integrations

### Neovim Integration

The [ravitemer/mcphub.nvim](https://github.com/ravitemer/mcphub.nvim) plugin provides seamless integration with Neovim, allowing direct interaction with MCP Hub from your editor:

- Execute MCP tools directly from Neovim
- Access MCP resources within your editing workflow
- Real-time status updates in Neovim
- Auto install mcp servers with marketplace addition

## REST API

### Health and Status

#### Health Check

```bash
GET /api/health
```

The health endpoint provides comprehensive status information including:
- Current hub state (starting, ready, restarting, restarted, stopping, stopped, error)
- Connected server statuses and capabilities
- Active SSE connection details
- Detailed connection metrics
- Error state details if applicable

Response:
```json
{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "4.1.1",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "2024-02-20T05:55:00.000Z"
      }
    ]
  },
  "workspaces": {
    "current": "40123",
    "allActive": {
      "40123": {
        "cwd": "/path/to/project-a",
        "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
        "pid": 12345,
        "port": 40123,
        "startTime": "2025-01-17T10:00:00.000Z",
        "state": "active",
        "activeConnections": 2,
        "shutdownStartedAt": null,
        "shutdownDelay": null
      }
    }
  }
}
```

#### List MCP Servers

```bash
GET /api/servers
```

#### Get Server Info

```bash
POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}
```

#### Refresh Server Capabilities

```bas

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ravitemer](https://github.com/ravitemer)
- **Source:** [ravitemer/mcp-hub](https://github.com/ravitemer/mcp-hub)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/mcp-hub

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ravitemer-mcp-hub
- Seller: https://agentstack.voostack.com/s/ravitemer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.