https://github.com/miguell-j/mcp-one
MCP-one is a central server that connects multiple independent MCP servers and exposes a unified interface to clients (LLMs or applications).
https://github.com/miguell-j/mcp-one
agents ai ai-agents docker mcp mcp-client mcp-server mcp-servers pydantic python server yaml yaml-configuration
Last synced: 3 months ago
JSON representation
MCP-one is a central server that connects multiple independent MCP servers and exposes a unified interface to clients (LLMs or applications).
- Host: GitHub
- URL: https://github.com/miguell-j/mcp-one
- Owner: Miguell-J
- License: mit
- Created: 2025-07-18T20:57:11.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-08-05T14:59:15.000Z (11 months ago)
- Last Synced: 2025-09-06T10:11:21.730Z (10 months ago)
- Topics: agents, ai, ai-agents, docker, mcp, mcp-client, mcp-server, mcp-servers, pydantic, python, server, yaml, yaml-configuration
- Language: Python
- Homepage:
- Size: 3.15 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.rst
- Authors: AUTHORS.rst
Awesome Lists containing this project
README
✨ MCP one – A Unified Hub for MCP Servers
MCP one is a lightweight, extensible, and blazing-fast hub to manage multiple MCPs (Model Context Protocol) servers in a single place.
---
## 🚀 Key Features
✅ **Dynamic Integration:** Add or remove MCP servers simply by editing `config.yaml`.
✅ **M × N → M + N:** Connect clients to a single hub instead of integrating each MCP directly.
✅ **Unified API:** Standardized `/tools`, `/call`, and `/servers` endpoints, regardless of underlying MCP differences.
✅ **Dynamic Endpoint Mapping:** Each MCP can expose custom routes or payloads. Map them with `endpoints`, `response_map`, and `payload_map`.
✅ **Health Monitoring:** Built-in `/health` and `/status` to monitor all connected servers.
✅ **Async & Scalable:** Built with FastAPI, `httpx`, and asyncio for top performance.
✅ **Plug & Play:** Works with any MCP server (GitHub MCP, SQL MCP, Jupyter MCP, or your own).
---
## 🏗️ Architecture
```text
┌───────────────────┐
│ MCP one API │◄──── Clients (LLMs, Apps, Services)
└─────────┬─────────┘
│
┌──────────────┼───────────────┐
│ │ │
┌────────────┐ ┌────────────┐ ┌────────────┐
│ MCP Server │ │ MCP Server │ │ MCP Server │
│ (GitHub) │ │ (SQL) │ │ (Jupyter)│
└────────────┘ └────────────┘ └────────────┘
```
💡 Each MCP server can define its own routes and payloads.
**MCP Hub normalizes everything.**
---
## ⚡ Getting Started
### 🔧 Prerequisites
* **Python 3.10+**
* A running MCP server (or use the included `dummy_mcp` example)
### 📦 Installation
```bash
git clone https://github.com//mcp-one.git
cd mcp-one
pip install -r requirements.txt
```
---
## ⚙️ Configuration
All server integrations are defined in `src/config.yaml`:
```yaml
servers:
- name: dummy
url: http://localhost:7000
description: Dummy MCP for testing
enabled: true
timeout: 30
retry_attempts: 3
endpoints:
health: /health
tools: /tools
call: /call
response_map:
tools_key: "" # empty means the response is a plain list
tool_name_field: "name"
tool_desc_field: "description"
payload_map:
tool_field: "tool"
args_field: "arguments"
hub:
host: "0.0.0.0"
port: 8000
debug: true
log_level: "INFO"
```
---
## 🚦 Running MCP Hub
Start the hub:
```bash
cd src
uvicorn app.main:app --reload
```
**MCP Hub will be available at:**
```
http://localhost:8000
```
---
## 📡 API Reference
| Endpoint | Method | Description |
| ------------------ | ------ | --------------------------------------------- |
| `/` | GET | Root information about the hub |
| `/health` | GET | Health status of the hub |
| `/status` | GET | Detailed status (servers, uptime, tools) |
| `/servers` | GET | List registered MCP servers |
| `/servers/refresh` | POST | Force refresh of all servers and tools |
| `/tools` | GET | List all available tools (across all servers) |
| `/call` | POST | Execute a tool on a specific server |
### 🛠 Example: Call a tool
```bash
curl -X POST http://localhost:8000/call \
-H "Content-Type: application/json" \
-d '{
"tool": "dummy.add_numbers",
"arguments": {"a": "5", "b": "7"}
}'
```
✅ **Response:**
```json
{
"success": true,
"result": {"sum": 12},
"server_name": "dummy",
"execution_time_ms": 8.37
}
```
---
## 🧩 Extending MCP Hub
MCP Hub supports **dynamic endpoint mappings**.
To add a new MCP server:
1. Add a new block in `config.yaml` with `endpoints`, `response_map`, and `payload_map`.
2. Restart the hub and refresh:
```bash
curl -X POST http://localhost:8000/servers/refresh
```
3. 🎉 Your new tools are now available through `/tools` and `/call`.
---
## 🌟 Why MCP one?
✔️ **Saves Integration Effort:** Forget wiring M×N connections for each client.
✔️ **Centralized Control:** One place to monitor, configure, and call tools.
✔️ **Future-Proof:** Add new MCP servers without changing code.
✔️ **Ready for Scale:** Designed with extensibility and high throughput in mind.
---
## 🤝 Contributing
We welcome contributions!
Check out [CONTRIBUTING.rst](CONTRIBUTING.rst) for guidelines.
---
## 📜 License
This project is licensed under the [MIT License](LICENSE).
---
Made by Miguel to the Open Source community.