MCPOrchestrator: The Consolidated Gateway for MCP Services

English | Français | 中文版

MCPOrchestrator simplifies the administration and scaling of heterogeneous MCP (Model Context Protocol) deployments by organizing them behind scalable Server-Sent Events (SSE) accessible paths—allowing access to all backend systems, specific nodes, or logical service collectives.

🌐 Interactive Showcase & Technical Manuals

• Reference Documentation: docs.mcphubx.com
• Live Demonstration Instance: demo.mcphubx.com

🚀 Core Capabilities

• Extensive MCP Backend Compatibility: Integrate virtually any existing MCP apparatus with minimal setup overhead.
• Unified Monitoring Console: Visualize current operational status and throughput metrics from a singular, intuitive Graphical User Interface (GUI).
• Protocol Versatility: Full compatibility supporting both local inter-process communication (stdio) and event streaming (SSE) MCP communication patterns.
• Zero-Downtime Configuration Adjustments: Provision, decommission, or modify backend MCP servers instantaneously without interrupting ongoing operations.
• Hierarchical Permission Structuring: Establish custom groupings for servers to streamline the application of security policies.
• Robust Security Foundation: Internal user ledger featuring role-based authorization enforced through JWT tokens and bcrypt hashing.
• Containerized Deployment Ready: Instant rollout capability using the provided container image.

🔧 Rapid Deployment Guide

Configuration File

Designate your service parameters within the mcp_settings.json artifact:

{ "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" } } } }

Containerized Launch

Recommended Method: Map your external configuration file:

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

or launch with default settings:

bash docker run -p 3000:3000 samanhappy/mcphub

Accessing the Control Panel

Navigate to http://localhost:3000 and authenticate using your credentials.

Initial Credentials: admin / admin123.

Panel Functionality Summary:

• Real-time telemetry display for all integrated MCP nodes.
• Ability to activate, deactivate, or revise node operational parameters.
• Utilities for managing server collections (groups).
• Administrative interface for access credential management.

Unified Streaming Interface (HTTP)

Current compatibility with certain proprietary AI assistants for streaming HTTP may be inconsistent. Users should utilize the SSE path or await subsequent revisions if stream issues persist.

Connect AI agents (e.g., Claude Desktop, Cursor, DeepChat, etc.) using:

http://localhost:3000/mcp

This Uniform Resource Identifier (URI) provides a consolidated, streamable HTTP interface spanning all provisioned MCP machinery. It enables you to:

• Forward execution requests to any defined MCP backend.
• Obtain instantaneous result feedback.
• Simplify integration across various AI toolsets.
• Employ a single address point for all underlying services.

Intelligent Dispatching (Beta):

Intelligent Dispatching represents MCPOrchestrator's advanced capability for context-aware function identification, employing vector similarity search to ascertain the optimal backend service(s) for a given user directive.

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

Operational Flow:

1. Service Indexing: All accessible MCP functionalities are transformed into vector representations and cataloged within a PostgreSQL database utilizing the pgvector extension.
2. Semantic Matching: User inputs are vectorized and compared against the stored service vectors via cosine similarity metrics.
3. Relevance Filtering: Dynamic confidence thresholds are applied to filter results, ensuring high precision and minimizing irrelevant responses.
4. Accurate Invocation: Identified services are executed directly, accompanied by appropriate argument validation.

Prerequisites for Intelligent Dispatching:

• A PostgreSQL installation configured with the pgvector module.
• Access to an embedding generation service (e.g., OpenAI API key or equivalent).
• Activation of the Intelligent Dispatching feature within the Orchestrator's configuration schema.

Group-Scoped Interfaces (Recommended for Production):

To target specific operational subsets of servers, utilize the path structured around defined collectives:

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

Where {group} corresponds to the identifier or moniker assigned to a managed server collection via the administration panel. This permits:

• Connecting to a curated subset of MCP servers grouped by functional domain.
• Segregating access rights for distinct AI workflows or team environments.
• Implementing fine-grained access control policies.

Node-Specific Interfaces:

For direct interaction with a singular MCP instance, employ the dedicated URI structure:

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

Where {server} is the registered alias of the target service. This grants singular access.

Conflict Resolution: Should a group name and a server name share an identical identifier, the group definition supersedes the individual server mapping.

Streaming HTTP Endpoint (Legacy Path)

Client applications (e.g., Claude Desktop, Cursor, DeepChat, etc.) can connect via:

http://localhost:3000/sse

For smart routing queries, use the variant:

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

For directed communication with server aggregates, the group-specific path is:

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

For direct communication with an isolated service instance, use:

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

🧑‍💻 Local Development Setup

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

This command initiates both the client-side and server-side components simultaneously, enabling live code updates.

Windows Users Note: Dual execution may be required: execute pnpm backend:dev and subsequently pnpm frontend:dev.

🛠️ Troubleshooting Common Issues

Configuration as a Reverse Proxy (e.g., Nginx)

If routing traffic through Nginx, the following directive is crucial for proper stream handling:

nginx proxy_buffering off

🔍 Technology Composition

• Server Side: Node.js runtime, Express framework, TypeScript language
• Client Side: React library, Vite bundler, Tailwind CSS styling
• Security Layer: JSON Web Tokens (JWT) and bcrypt hashing algorithm
• Communication Standard: Model Context Protocol SDK implementation

👥 Community Engagement

We welcome all forms of contribution towards enhancing this utility!

• Novel features and performance tuning
• Enhancements to the informational documentation
• Reporting and patching of functional defects
• Localization efforts and conceptual feedback

Join our Discord server for dialogue and mutual assistance.

❤️ Patronage

If this utility proves valuable to your operations, consider providing financial support:

🌟 Growth Trajectory

📄 Licensing

Distributed under the terms of the Apache 2.0 License.