Unified MCP Endpoint Manager

English | 简体中文

Licensing Terms

This software is distributed under the terms of the GNU General Public License version 3.0; refer to the LICENSE document for exhaustive particulars.

System Synopsis

This component, implemented in Python, functions as a primary aggregation hub. It establishes connections to, and consolidates the feature sets of, multiple underlying MCP engines (regardless of whether their communication style is Stdio or SSE). The resulting unified capabilities are then broadcast to consuming MCP clients through a singular SSE stream accessible at the /sse path.

Key Benefits:

1. Streamlined Client Interface: Consumers interact only with the Gateway's singular network address, completely removing the burden of individual backend server address management.
2. Feature Consolidation & Control: Pools diverse tool capabilities sourced from various origins, establishing a robust foundation for developing specialized, high-value agent systems.

Project Directory Layout

plaintext . ├── config.json # Primary configuration artifact: Defines the peripheral MCP servers managed by the system. ├── main.py # Initialization script: Handles argument parsing, logging setup, and web service bootstrap. ├── bridge_app.py # Core Starlette logic: Manages request relaying and the maintenance of SSE client sessions. ├── client_manager.py # Session handler: Oversees the initiation and persistence of communication channels with upstream MCP nodes. ├── capability_registry.py # Feature catalog: Dynamically identifies, catalogs, and maintains the inventory of exposed functionalities. ├── config_loader.py # Parameter parsing utility: Securely loads and strictly validates the structure of config.json. ├── errors.py # Custom exception definitions: Stores project-specific error classes (e.g., setup failures, upstream communication faults). ├── mods/ # Repository for bundled/example backend server utility scripts. └── logs/ # Runtime data directory: Where execution logs are persistently stored (created automatically).

Deployment Prerequisites

This application requires a Python environment. Utilizing uv for dependency and environment isolation is the recommended methodology.

1. Acquire Source Code

   bash git clone https://github.com/trtyr/MCP-Gateway.git cd MCP-Gateway

2. Environment Setup

   bash

   Provision the isolated environment

   uv venv

   Activate the environment

   Unix-like systems

   source .venv/bin/activate

   Windows environments

   .venv\Scripts\activate

3. Dependency Installation bash # Install all required libraries listed in pyproject.toml uv sync

With these prerequisites met, the system is prepared for execution.

Initial Execution Guide

Accessing Startup Parameters

Invoke the utility with the -h or --help flag to display all configurable launch arguments:

bash

Windows execution wrapper

uv run python .\main.py -h

Linux/macOS execution wrapper

uv run python ./main.py -h

The resultant output will resemble this structure:

plaintext usage: main.py [-h] [--host HOST] [--port PORT] [--log-level {debug,info,warning,error,critical}]

Start MCP_Bridge_Server v3.0.0

options: -h, --help show this help message and exit --host HOST Host address (default: 0.0.0.0) --port PORT Port (default: 9000) --log-level {debug,info,warning,error,critical} Set file logging level (default: info)

Launching the System

Observation: Visual enhancements previously provided by the Rich library have been deprecated; operational reality upon execution dictates the definitive output.

Execute the server using uv run python main.py. Parameters for network binding (host, port), and verbosity (log-level) are optional:

bash

Bind to all interfaces on port 9000, use verbose debugging logs

uv run python .\main.py --host 0.0.0.0 --port 9000 --log-level debug

Upon initialization, the system console will typically display status information, connection details, and a summary of the integrated toolsets (though visual styling may be absent).

Connecting MCP Clients

Observation: Visual enhancements previously provided by the Rich library have been deprecated; operational reality upon execution dictates the definitive output.

Once the Orchestrator is active, any client adhering to the MCP specification (e.g., Cline, Cursor, proprietary desktops) can connect to the exposed SSE stream endpoint.

The default access point is http://<Server_IP_Address>:9000/sse (assuming the default port).

Demonstration (Using ChatWise Connect client):

1. Designate the connection modality as SSE.
2. Input the Gateway's URL (e.g., http://127.0.0.1:9000/sse).
3. Activate the connection sequence.

Upon successful establishment, the client interface will reflect the complete set of backend tools harmonized by the Gateway:

Operational Logging

System execution records are automatically archived in the logs sub-directory within the project root. Log filenames incorporate timestamps and severity levels, facilitating efficient diagnostic tracing.

logs/ ├── log_20240801_103000_INFO.log └── log_20240801_110000_DEBUG.log ...

Configuration Artifact (config.json)

The primary configuration file, config.json, resides at the project's root level. It dictates which peripheral MCP servers the Orchestrator must interface with and supervise.

Each top-level entry defines a single backend server. The key assigned serves as the unique identifier (which becomes the namespace prefix for its associated features), and its corresponding value details the connection parameters.

Two distinct connection methodologies are supported:

• stdio: Facilitates interaction with an MCP server instance executed locally, communicating via standard input/output streams.
• sse: Connects to an already operational MCP server, accessible either locally or remotely, utilizing the Server-Sent Events protocol.

Stdio Protocol Setup

Ideal for local MCP processes whose lifecycle management (starting/stopping) is delegated to the Orchestrator.

Required Parameters:

• type (mandatory): Must be set to the literal string "stdio".
• command (mandatory): The executable invocation string used to bootstrap the process (e.g., python, uv, node, or a fully qualified path to the binary/script).
• args (mandatory): An ordered sequence (JSON Array of strings) of parameters relayed to the command.
• env (optional): A key-value mapping (JSON Object) defining custom environment variables for the spawned child process. If omitted, standard inherited environment variables are used.

Configuration Example:

{ "powershell_adapter": { "type": "stdio", "command": "python", "args": ["servers/powershell_server.py"] }, "custom_etl_node": { "type": "stdio", "command": "/opt/bin/mcp_processor", "args": ["--mode", "fast"], "env": { "SECRET_TOKEN": "secure_value" } } }

Operational Mechanism: Upon system launch, the Orchestrator invokes the process defined by command and args (applying env if present). Communication occurs directly through the established stdin/stdout channels. Termination of the Orchestrator triggers an attempt to gracefully halt these associated child processes.

SSE Protocol Setup

Intended for linking with already running MCP services (local or network-accessible), or when the Orchestrator is tasked with initiating a local SSE listener process prior to connection.

Required Parameters:

• type (mandatory): Must be set to the literal string "sse".
• url (mandatory): The complete Uniform Resource Locator (HTTP/HTTPS) pointing to the backend MCP server's SSE data stream.
• command (conditional): If present, the Orchestrator executes this command at initialization to boot the local SSE listener process.
• args (conditional, only with command): Parameters passed to the command used for local process spawning.
• env (conditional, only with command): Environmental variables configured for the child process launched locally.

Example 1: Interfacing with a Pre-existing Remote Service

{ "external_analytics_feed": { "type": "sse", "url": "https://data.corp.net/mcp/stream" } }

Example 2: Gateway Manages Local SSE Server Lifecycle

{ "internal_dashboard_api": { "type": "sse", "url": "http://127.0.0.1:8888/events", "command": "node", "args": ["server/dashboard_listener.js", "--port", "8888"], "env": { "PROFILE": "production" } } }

Operational Mechanism:

• Only url supplied: The system immediately initiates a connection attempt to the specified endpoint.
• url, command, args provided: The Orchestrator first executes the defined command and args (assuming this process binds to the network address implied by url). Following a brief mandated pause (LOCAL_SSE_STARTUP_DELAY defined internally), it attempts stream connection to url. Process termination in the Orchestrator attempts to kill this spawned local server instance.

Integrating External Tools

Illustrations detailing the integration of third-party MCP implementations into config.json.

Stdio Integration Example: Playwright MCP Adapter

Assume integration of the Playwright MCP utility (@playwright/mcp).

1. Startup Method Identification: Playwright MCP is generally invoked via npx @playwright/mcp@latest, which relies on the Node.js execution runtime.

2. Configuration Entry:

   { // ... existing entries ... "browser_automation": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] } // ... existing entries ... }

   Here, command is set to npx, and args specifies the package reference.

3. Restart Required: Apply changes to config.json and relaunch the Orchestrator.

Upon successful startup, features prefixed with browser_automation/ (e.g., browser_automation/navigate) will be visible in the system output and client interfaces.

SSE Integration Example: ENScan_GO (Local Bootstrap)

Consider integrating ENScan_GO, a Go binary requiring execution as ./enscan --mcp to expose an SSE interface on http://localhost:8080.

1. Acquire Binary: Place the executable (e.g., enscan-v1.2.1-linux-amd64) in a location accessible by the Gateway (e.g., the servers/ folder or a system-wide PATH directory).

2. Configuration Entry:

   { // ... existing entries ... "network_scanner": { "type": "sse", "url": "http://127.0.0.1:8080/sse", // Address the Go program listens on "command": "./servers/enscan-v1.2.1-linux-amd64", // Path to the executable "args": ["--mcp"] // Arguments for the executable } // ... existing entries ... }

   This configuration instructs the Gateway to connect to the specified url after first launching the scanner via its command and args.

3. Restart Required: Save config.json and restart the Orchestrator.

The Gateway will manage the lifecycle, starting ENScan_GO and then connecting to its SSE stream. Tools beginning with the network_scanner/ prefix will subsequently become available.