mcp-hub

mcp-hub is a lightweight control plane and local stdio agent for managing MCP sources across AI coding tools.

It lets Codex, Claude Code, OpenCode, and other MCP clients connect to one local agent while the actual upstream MCP services are configured from a remote control plane.

• npm package: @a1ua/mcp-hub
• Repository: https://github.com/aiua-dev/mcp-hub
• License: MIT

Overview

MCP tools are often installed and configured per client. As the number of tools grows, keeping every local client in sync becomes repetitive and error-prone.

mcp-hub separates the system into two parts:

• Local agent
  • Runs as a stdio MCP server.
  • Loads workspace configuration from a control-plane API.
  • Connects to upstream MCP services from the local machine.
  • Falls back to cached configuration when the control plane is temporarily unavailable.
• Control plane
  • Maintains MCP sources, exposed tools, and hosted source definitions.
  • Provides configuration endpoints for local agents.
  • Includes a web console for managing sources and copied client configs.

Features

• One local stdio entrypoint for multiple MCP clients.
• Remote workspace configuration with local cache fallback.
• Tool naming and exposure control.
• Support for multiple upstream source types:
  • direct-http
  • local-stdio
  • hosted-npm
  • hosted-single-file
• Codex-friendly TOML output with explicit type = "stdio".
• Shell-wrapped npx command generation for GUI clients with limited $PATH.
• Optional export profiles for exposing different source sets as separate MCP servers.

Install

Use the published local agent directly with npx:

npx -y @a1ua/mcp-hub \
  --base-url https://your-control-plane.example.com \
  --workspace mcp-hub \
  --token your-token

Or install it globally:

npm install -g @a1ua/mcp-hub

Client Setup

Codex

codex mcp add mcp-hub -- \
  npx -y @a1ua/mcp-hub \
  --base-url https://your-control-plane.example.com \
  --workspace mcp-hub \
  --token your-token

You can also write the server configuration directly:

[mcp_servers."mcp-hub"]
type = "stdio"
command = "/bin/sh"
args = ["-lc", "PATH=\"/opt/homebrew/bin:/usr/local/bin:$PATH\"; if [ -d \"$HOME/.nvm/versions/node\" ]; then for dir in \"$HOME\"/.nvm/versions/node/*/bin; do [ -d \"$dir\" ] && PATH=\"$dir:$PATH\"; done; fi; cd \"$HOME\"; exec 'npx' '-y' '@a1ua/mcp-hub' '--base-url' 'https://your-control-plane.example.com' '--workspace' 'mcp-hub' '--token' 'your-token'"]

Config URL Mode

Use --config-url when the control plane gives you a full workspace or export config endpoint:

npx -y @a1ua/mcp-hub \
  --config-url https://your-control-plane.example.com/v1/workspaces/mcp-hub/config \
  --workspace mcp-hub \
  --token your-token

CLI Options

Option	Description
--base-url	Control-plane base URL. The agent resolves /v1/workspaces/<workspace>/config.
--config-url	Full configuration URL. Takes precedence over --base-url.
--workspace	Workspace ID and local cache key.
--token	Bearer token passed directly on the command line.
--token-env	Environment variable name used to read the Bearer token.
--cache-dir	Custom local cache directory.

The same settings can also be supplied through environment variables:

• MCP_AGENT_BASE_URL
• MCP_AGENT_CONFIG_URL
• MCP_AGENT_WORKSPACE
• MCP_AGENT_TOKEN
• MCP_AGENT_TOKEN_ENV
• MCP_AGENT_CACHE_DIR

Project Structure

.
├── apps
│   ├── control-plane-api     # Fastify API and hosted-source runtime management
│   └── control-plane-web     # React control-plane console
├── packages
│   ├── agent                 # Published local stdio agent
│   ├── runtime               # MCP aggregation runtime
│   └── shared                # Shared schemas and config mapping
└── docs                      # Architecture and product notes

Development

Install dependencies:

pnpm install

Run the development helper:

pnpm go

Run API and web console separately:

pnpm dev:api
pnpm dev:web

Run checks:

pnpm -r test
pnpm build

Control-Plane Contract

The local agent expects a workspace config endpoint that returns a JSON workspace configuration.

With --base-url https://your-control-plane.example.com --workspace mcp-hub, the agent requests:

https://your-control-plane.example.com/v1/workspaces/mcp-hub/config

With export profiles, the control plane can provide separate config URLs for different MCP server views.

Current Scope

mcp-hub focuses on local MCP aggregation and configuration delivery. It is not intended to be a multi-tenant SaaS backend out of the box.

The current implementation is best suited for:

• personal MCP workspaces,
• small team tool setups,
• self-hosted control planes,
• experiments with hosted or generated MCP sources.

Roadmap

• Improve the public setup wizard and install documentation.
• Expand hosted-source lifecycle management.
• Add more automated coverage around source discovery and export profiles.
• Refine the web console for clearer source, tool, and export workflows.

License

MIT