Multi MCP Server

How to use

You connect to the proxy using an MCP-compatible client, then choose either STDIO or SSE transport depending on your environment. In STDIO mode, you pipe data to and from the proxy for CLI-style tool chaining. In SSE mode, you expose an HTTP SSE endpoint so remote agents and browser-based tools can access the connected MCP servers through the proxy. The proxy automatically namespaces tools from different servers to avoid conflicts and exposes a single access point for all connected backends.

How to install

Prerequisites: ensure you have Python and the tooling used by the project available on your system. You will clone the project, install dependencies, and prepare the environment before running the proxy.

# Clone the repository
git clone https://github.com/kfirtoledo/multi-mcp.git
cd multi-mcp

# Install using uv (recommended)
uv venv
uv pip install -r requirements.txt

Run in STDIO or SSE mode locally

Choose the mode that fits your workflow. STDIO is ideal for local, CLI-style tool chaining. SSE is suitable for remote access and browser-based interactions.

# STDIO mode
uv run main.py --transport stdio

# SSE mode
uv run main.py --transport sse

Production mode with external MCP servers

For production deployments that connect to external MCP servers, set your environment variables and start the production workflow using the provided startup script.

# Set required environment variables
export GITHUB_PERSONAL_ACCESS_TOKEN="your-token-here"
export BRAVE_API_KEY="your-api-key-here"
export MULTI_MCP_API_KEY="your-secret-key"  # Optional, for authentication

# Run the startup script
./start-server.sh

Configuration patterns you’ll use

The proxy can initialize from a local JSON config or connect to remote MCP servers via SSE. A local setup defines which MCP-compatible servers to spawn at startup, while a remote setup uses an SSE URL for each backend.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["./tools/get_weather.py"]
    },
    "calculator": {
      "command": "python",
      "args": ["./tools/calculator.py"]
    }
  }
}
```

This config initializes two MCP servers at startup. Tool names are namespaced internally as `server_name::tool_name` to avoid conflicts; for example, a server named `calculator` exposing an `add` tool would be referenced as `calculator::add`.

Dynamic server management (SSE only)

When running in SSE mode, you can add, remove, or list MCP servers at runtime through HTTP endpoints.

GET  /mcp_servers          # List active MCP servers
POST /mcp_servers          # Add a new MCP server
DELETE /mcp_servers/{name} # Remove an MCP server by name
GET  /mcp_tools            # List all tools and their sources

Examples: adding a new server at runtime

You can post a JSON payload to add a new MCP server while the proxy is running.

curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  --data @add_server.json
```

add_server.json
```json
{
  "mcpServers": {
    "unit_converter": {
      "command": "python",
      "args": ["./tools/unit_converter.py"]
    }
  }
}

Tools, namespaces, and how tools are exposed

Tools from different MCP servers are exposed with a namespace to prevent collisions. For example, a weather server exposing a get_weather tool would be referenced as weather::get_weather.

Docker

Containerize and run the SSE server in Kubernetes or locally with Docker. Build the image and run it with port exposure to access the SSE endpoint.

# Build the image
make docker-build

# Run locally with port exposure
make docker-run

Kubernetes

Deploy the proxy in a Kubernetes cluster using the provided manifests. The default manifest exposes the SSE server via a NodePort for external access.

kind create cluster --name multi-mcp-test
kind load docker-image multi-mcp --name multi-mcp-test
kubectl apply -f k8s/multi-mcp.yaml

# Access the SSE endpoint from outside the cluster
http://<kind-node-ip>:30080/sse

Connecting to MCP clients

Once the proxy is running, connect with any MCP-compatible client. You can integrate with tooling ecosystems that support MCP, such as LangGraph, to access tools from multiple backend MCP servers.

Example integrations can be built with adapters that connect to the proxy’s SSE endpoint and expose the combined tool surface to your language models or agents.

Environment and quick-start notes

Prepare an environment for client usage by ensuring you have an MCP-compatible client and an environment file containing necessary credentials. A sample environment setup may include model configuration and API keys for your tooling.

get_weather

Fetches current weather data using the weather MCP server tool

calculator

Performs arithmetic calculations via the calculator MCP server tool

unit_converter

Converts units using the unit_converter MCP server tool