MCPHub

What is MCPHub about?

MCPHub offers a unified hub that aggregates many MCP servers into a single, configurable platform. It exposes a streamable HTTP (SSE) endpoint and group‑ or server‑specific routes, enabling AI clients to interact with any configured tool without handling each server individually.

How to use MCPHub?

1. Create a configuration – add a mcp_settings.json file describing each MCP server (command, arguments, environment variables).
2. Run the hub – use Docker (recommended) or start the Node.js backend directly. Example Docker command:

   docker run -p 3000:3000 -v ./mcp_settings.json:/app/mcp_settings.json -v ./data:/app/data samanhappy/mcphub
   

3. Access the dashboard – open http://localhost:3000, log in (default admin/admin123), and manage servers, groups, and users.
4. Consume the endpoints – send requests to http://localhost:3000/mcp for the unified stream, or use http://localhost:3000/mcp/{group} and http://localhost:3000/mcp/{server} for scoped access. Smart routing is available via /$smart paths when enabled.

Key Features

• Broad MCP server support – plug in any MCP server with minimal setup.
• Centralized real‑time dashboard – monitor status, performance, and control servers from one UI.
• Hot‑swappable configuration – add, remove, or update servers without downtime.
• Group‑based access control – organize servers into logical groups for permission management.
• Secure JWT & bcrypt authentication – role‑based user management.
• Docker‑ready – one‑click container deployment.
• Experimental Smart Routing – vector‑based tool discovery using PostgreSQL + pgvector and OpenAI embeddings.
• Multiple endpoint styles – unified HTTP, server‑specific, group‑specific, and legacy SSE.

Use Cases

• AI tool orchestration – expose many specialized AI utilities (maps, web automation, Slack bots) through a single endpoint for downstream models.
• Team collaboration – create groups per project or department, granting scoped access without exposing all servers.
• Rapid prototyping – spin up new MCP services locally, add them to the hub, and test interactions instantly.
• Production monitoring – use the dashboard to watch health and performance of all integrated MCP services.
• Smart tool selection – let the hub automatically select the most relevant tool for a task via semantic search.

FAQ

Q: Do I need to run each MCP server separately? A: No. Define the server command in mcp_settings.json; MCPHub will launch and manage them automatically.

Q: Can I use the hub without Docker? A: Yes. Clone the repo, run pnpm install and pnpm dev (or pnpm backend:dev / pnpm frontend:dev on Windows).

Q: How does authentication work? A: Users are stored in the hub’s database with bcrypt‑hashed passwords. JWT tokens are issued on login and used to protect API endpoints.

Q: What is the difference between the /mcp and /sse endpoints? A: /mcp returns a standard HTTP stream compatible with most AI clients; /sse is the legacy Server‑Sent Events endpoint slated for deprecation.

Q: How do I enable Smart Routing? A: Install PostgreSQL with the pgvector extension, provide an OpenAI (or compatible) API key, and enable the feature in the hub settings.

Q: Can I customize the port? A: Yes. Set the PORT environment variable when running the container or the Node.js process.

MCPHub: The Unified Hub for Model Context Protocol (MCP) Servers

English | Français | 中文版

MCPHub makes it easy to manage and scale multiple MCP (Model Context Protocol) servers by organizing them into flexible Streamable HTTP (SSE) endpoints—supporting access to all servers, individual servers, or logical server groups.

🌐 Live Demo & Docs

• Documentation: docs.mcphubx.com
• Demo Environment: demo.mcphubx.com

🚀 Features

• Broadened MCP Server Support: Seamlessly integrate any MCP server with minimal configuration.
• Centralized Dashboard: Monitor real-time status and performance metrics from one sleek web UI.
• Flexible Protocol Handling: Full compatibility with both stdio and SSE MCP protocols.
• Hot-Swappable Configuration: Add, remove, or update MCP servers on the fly — no downtime required.
• Group-Based Access Control: Organize servers into customizable groups for streamlined permissions management.
• Secure Authentication: Built-in user management with role-based access powered by JWT and bcrypt.
• Docker-Ready: Deploy instantly with our containerized setup.

🔧 Quick Start

Configuration

Create a mcp_settings.json file to customize your server settings:

{
  "mcpServers": {
    "amap": {
      "command": "npx",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your-api-key"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-bot-token",
        "SLACK_TEAM_ID": "your-team-id"
      }
    }
  }
}

Docker Deployment

Recommended: Mount your custom config:

docker run -p 3000:3000 -v ./mcp_settings.json:/app/mcp_settings.json -v ./data:/app/data samanhappy/mcphub

or run with default settings:

docker run -p 3000:3000 samanhappy/mcphub

Access the Dashboard

Open http://localhost:3000 and log in with your credentials.

Note: Default credentials are admin / admin123.

Dashboard Overview:

• Live status of all MCP servers
• Enable/disable or reconfigure servers
• Group management for organizing servers
• User administration for access control

Streamable HTTP Endpoint

As of now, support for streaming HTTP endpoints varies across different AI clients. If you encounter issues, you can use the SSE endpoint or wait for future updates.

Connect AI clients (e.g., Claude Desktop, Cursor, DeepChat, etc.) via:

http://localhost:3000/mcp

This endpoint provides a unified streamable HTTP interface for all your MCP servers. It allows you to:

• Send requests to any configured MCP server
• Receive responses in real-time
• Easily integrate with various AI clients and tools
• Use the same endpoint for all servers, simplifying your integration process

Smart Routing (Experimental):

Smart Routing is MCPHub's intelligent tool discovery system that uses vector semantic search to automatically find the most relevant tools for any given task.

http://localhost:3000/mcp/$smart

How it Works:

1. Tool Indexing: All MCP tools are automatically converted to vector embeddings and stored in PostgreSQL with pgvector
2. Semantic Search: User queries are converted to vectors and matched against tool embeddings using cosine similarity
3. Intelligent Filtering: Dynamic thresholds ensure relevant results without noise
4. Precise Execution: Found tools can be directly executed with proper parameter validation

Setup Requirements:

To enable Smart Routing, you need:

• PostgreSQL with pgvector extension
• OpenAI API key (or compatible embedding service)
• Enable Smart Routing in MCPHub settings

Group-Specific Endpoints (Recommended):

For targeted access to specific server groups, use the group-based HTTP endpoint:

http://localhost:3000/mcp/{group}

Where {group} is the ID or name of the group you created in the dashboard. This allows you to:

• Connect to a specific subset of MCP servers organized by use case
• Isolate different AI tools to access only relevant servers
• Implement more granular access control for different environments or teams

Server-Specific Endpoints: For direct access to individual servers, use the server-specific HTTP endpoint:

http://localhost:3000/mcp/{server}

Where {server} is the name of the server you want to connect to. This allows you to access a specific MCP server directly.

Note: If the server name and group name are the same, the group name will take precedence.

SSE Endpoint (Deprecated in Future)

Connect AI clients (e.g., Claude Desktop, Cursor, DeepChat, etc.) via:

http://localhost:3000/sse

For smart routing, use:

http://localhost:3000/sse/$smart

For targeted access to specific server groups, use the group-based SSE endpoint:

http://localhost:3000/sse/{group}

For direct access to individual servers, use the server-specific SSE endpoint:

http://localhost:3000/sse/{server}

🧑‍💻 Local Development

git clone https://github.com/samanhappy/mcphub.git
cd mcphub
pnpm install
pnpm dev

This starts both frontend and backend in development mode with hot-reloading.

For windows users, you may need to start the backend server and frontend separately: pnpm backend:dev, pnpm frontend:dev.

🛠️ Common Issues

Using Nginx as a Reverse Proxy

If you are using Nginx to reverse proxy MCPHub, please make sure to add the following configuration in your Nginx setup:

proxy_buffering off

🔍 Tech Stack

• Backend: Node.js, Express, TypeScript
• Frontend: React, Vite, Tailwind CSS
• Auth: JWT & bcrypt
• Protocol: Model Context Protocol SDK

👥 Contributing

Contributions of any kind are welcome!

• New features & optimizations
• Documentation improvements
• Bug reports & fixes
• Translations & suggestions

Welcome to join our Discord community for discussions and support.

❤️ Sponsor

If you like this project, maybe you can consider:

🌟 Star History

📄 License

Licensed under the Apache 2.0 License.