multi-mcp

# **Multi MCP** A flexible and dynamic **Multi-MCP** Proxy Server that acts as a single MCP server while connecting to and routing between multiple backend MCP servers over `STDIO` or `SSE`. <p align="center"> <img src="assets/multi-mcp-diagram.png" alt="Multi-MCP Server Architecture" width="300"/> </p> ## 🚀 Features - ✅ Supports both `STDIO` and `SSE` transports - ✅ Can connect to MCP servers running in either `STDIO` or `SSE` mode - ✅ Proxies requests to multiple MCP servers - ✅ Automatically initializes capabilities (tools, prompts, resources) from connected servers - ✅ Dynamically **add/remove MCP servers** at runtime (via HTTP API) - ✅ Supports tools with the same name on different servers (using namespacing) - ✅ Deployable on Kubernetes, exposing a single port to access all connected MCP servers through the proxy ## 📦 Installation To get started with this project locally: ```bash # 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 ``` ## 🖥️ Running Locally You can run the proxy locally in either `STDIO` or `SSE` mode depending on your needs: ### 1. STDIO Mode For CLI-style operation (pipe-based communication). Used for chaining locally executed tools or agents. ```bash uv run main.py --transport stdio ``` ### 2. SSE Mode Runs an HTTP SSE server that exposes a `/sse` endpoint. Useful for remote access, browser agents, and network-based tools. ```bash uv run main.py --transport sse ``` **Note:** You can also configure the host and port using `--host` / `--port` arguments. ## ⚙️ Configuration The proxy is initialized using a JSON config (default: `./mcp.json`): ```json { "mcpServers": { "weather": { "command": "python", "args": ["./tools/get_weather.py"] }, "calculator": { "command": "python", "args": ["./tools/calculator.py"] } } } ``` This config defines the initial list of MCP-compatible servers to spawn and connect at startup. **Note:** Tool names are namespaced internally as `server_name::tool_name` to avoid conflicts and allow multiple servers to expose tools with the same base name. For example, if an MCP server named `calculator` provides an `add` tool, it will be referenced as `calculator::add`. You can also connect to a remote MCP server using SSE: ```json { "mcpServers": { "weather": { "url": "http://127.0.0.1:9080/sse" } } } ``` More examples can be found in the [examples/config/](./examples/config/) directory. ## 🔄 Dynamic Server Management (SSE only) When running in SSE mode, you can **add/remove/list MCP servers at runtime** via HTTP endpoints: | Method | Endpoint | Description | |--------|------------------------|-----------------------------| | `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` | Lists all available tools and their serves sources| ### Example to add a new server: ```bash 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"] } } } ``` ## 🐳 Docker You can containerize and run the SSE server in K8s: ```bash # Build the image make docker-build # Run locally with port exposure make docker-run ``` ## Kubernetes You can deploy the proxy in a Kubernetes cluster using the provided manifests. ### Run with [Kind](https://kind.sigs.k8s.io/) To run the proxy locally using Kind: ```bash kind create cluster --name multi-mcp-test kind load docker-image multi-mcp --name multi-mcp-test kubectl apply -f k8s/multi-mcp.yaml ``` ### Exposing the Proxy The K8s manifest exposes the SSE server via a NodePort (30080 by default): You can then connect to the SSE endpoint from outside the cluster: ```sh http://<kind-node-ip>:30080/sse ``` ## Connecting to MCP Clients Once the proxy is running, you can connect to it using any MCP-compatible client — such as a LangGraph agent or custom MCP client. For example, using the langchain_mcp_adapters client, you can integrate directly with LangGraph to access tools from one or more backend MCP servers. See [`examples/connect_langgraph_client.py`](examples/connect_langgraph_client.py) for a working integration example. Make sure your environment is set up with: - An MCP-compatible client (e.g. LangGraph) - .env file containing: ```env MODEL_NAME=<your-model-name> BASE_URL=<https://your-openai-base-url> OPENAI_API_KEY=<your-api-key> ``` ## Inspiration This project is inspired by and builds on ideas from two excellent open-source MCP projects: - [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) by @sparfenyuk - [`fastmcp`](https://github.com/jlowin/fastmcp) by @jlowin