Content
# **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
