[](https://datalayer.ai) [](https://github.com/sponsors/datalayer) # ✨ MCP Compose [](https://pypi.org/project/mcp-compose) [](https://github.com/datalayer/mcp-compose/actions/workflows/build.yml) [](https://github.com/datalayer/mcp-compose) [](https://www.python.org/downloads/) [](LICENSE) [](Dockerfile) > **Similar to Docker Compose - Orchestrate Model Context Protocol (MCP) servers with management capabilities, REST API, and Web UI.** ## 🎯 Overview MCP Compose is a comprehensive solution for managing multiple MCP servers in a unified environment. It provides automatic discovery, intelligent composition, protocol translation, real-time monitoring, and a beautiful web interface for managing your MCP infrastructure. ### Key Capabilities 🔧 **Multiple MCP Servers Management** - Start, stop, and monitor multiple MCP servers from a single interface 🌐 **REST API** - Complete REST API with 32 endpoints for programmatic control 🎨 **Modern Web UI** - Beautiful React-based interface with real-time updates 🔄 **Protocol Translation** - Seamlessly translate between STDIO and SSE protocols 📊 **Real-Time Monitoring** - Live metrics, logs, and health checks 🔐 **Security First** - Token authentication, CORS support, rate limiting 📦 **Easy Deployment** - Docker support with docker-compose orchestration 🧪 **Well Tested** - 95% test coverage with 265+ tests 📚 **Comprehensive Docs** - Full API reference, user guide, and deployment guide ## 🚀 Quick Start ### Installation ```bash # Install from PyPI pip install mcp-compose # Or install from source git clone https://github.com/datalayer/mcp-compose.git cd mcp-compose pip install -e . ``` ### Using Docker (Recommended) ```bash # Clone repository git clone https://github.com/datalayer/mcp-compose.git cd mcp-compose # Start with docker-compose (includes Prometheus & Grafana) docker-compose up -d # Access the Web UI open http://localhost:8000 ``` ### Using CLI ```bash # Start the server with Web UI mcp-compose serve --config examples/ui/mcp_compose.toml # Access Web UI at http://localhost:8000 # Access API at http://localhost:8000/api/v1 # Access API docs at http://localhost:8000/docs # Discover available MCP servers mcp-compose discover # Invoke a tool mcp-compose invoke-tool calculator:add '{"a": 5, "b": 3}' ``` ### Using Python API ```python from mcp_compose import MCPServerComposer # Create composer and start servers composer = MCPServerComposer() composer.load_config("config.toml") # Start all servers for server in composer.servers.values(): await composer.start_server(server.name) # List available tools tools = await composer.list_tools() print(f"Available tools: {[t.name for t in tools]}") # Invoke a tool result = await composer.invoke_tool("calculator:add", {"a": 5, "b": 3}) print(f"Result: {result}") ``` ## 🎨 Web UI Features The modern web interface provides: - **📊 Dashboard** - Overview of all servers, tools, and system metrics - **🖥️ Server Management** - Start, stop, restart servers with real-time status - **🔧 Tool Browser** - Search and invoke tools with interactive forms - **⚙️ Configuration Editor** - Edit and validate configuration files - **📋 Log Viewer** - Real-time log streaming with filtering - **📈 Metrics Dashboard** - Charts for CPU, memory, and request metrics - **🔄 Translator Management** - Create and manage protocol translators - **⚙️ Settings** - Configure theme, API settings, and preferences ## 📖 Documentation - **[User Guide](docs/USER_GUIDE.md)** - Complete guide for using MCP Compose - **[API Reference](docs/API_REFERENCE.md)** - Full REST API and Python API documentation - **[Deployment Guide](docs/DEPLOYMENT.md)** - Production deployment with Docker & Kubernetes - **[Architecture](ARCHITECTURE.md)** - System architecture and design decisions ## 💡 What can you use MCP Compose for? - Local AI development environments: Spin up multiple MCP servers (tools, data sources, agents) on your laptop with one command, inspect them live, and iterate faster. - Agent tool ecosystems: Compose and expose tools from multiple MCP servers into a single, unified interface for AI agents — with clear conflict resolution strategies. - Protocol bridging: Run legacy or CLI-based MCP servers over STDIO while exposing them to modern clients via SSE, without rewriting anything. - Team & platform workflows: Standardize how MCP servers are started, monitored, and secured across teams using Docker, tokens, and a shared control plane. - Observability & debugging: Track logs, metrics, and server health in real time through a Web UI or REST API — ideal for diagnosing tool behavior during agent runs. - Production-ready orchestration: Deploy multiple MCP servers with authentication, monitoring, and lifecycle management — without building custom glue code. ✨ Key capabilities that enable these use cases: - Unified multi-server start / stop / monitor - REST API + modern React-based Web UI - Tool discovery and intelligent composition - Programmatic control via Python API - Real-time metrics, logs, and monitoring ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Web UI (React) │ │ Dashboard │ Servers │ Tools │ Config │ Logs │ Metrics │ └──────────────────────────┬──────────────────────────────────┘ │ HTTP/WebSocket ┌──────────────────────────┴──────────────────────────────────┐ │ REST API (FastAPI) │ │ /servers │ /tools │ /config │ /translators │ /metrics │ └──────────────────────────┬──────────────────────────────────┘ │ ┌──────────────────────────┴──────────────────────────────────┐ │ MCP Compose Core │ │ Server Manager │ Tool Broker │ Config Manager │ └───────┬──────────┬──────────┬──────────┬────────────────────┘ │ │ │ │ ┌────┴───┐ ┌───┴────┐ ┌───┴────┐ ┌───┴────┐ │ Server │ │ Server │ │ Server │ │ Server │ │ A │ │ B │ │ C │ │ D │ └────────┘ └────────┘ └────────┘ └────────┘ ``` ## ✨ Core Features ### Server Management ## ✨ Core Features ### Server Management - **Multi-Server Orchestration** - Run multiple MCP servers simultaneously - **Lifecycle Management** - Start, stop, restart, and monitor server health - **Auto-restart** - Automatically restart failed servers - **Environment Isolation** - Each server runs in its own isolated environment - **Configuration Hot-Reload** - Update configuration without restarting ### Tool & Prompt Composition - **Automatic Discovery** - Find tools and prompts from all running servers - **Intelligent Composition** - Combine capabilities from multiple sources - **Conflict Resolution** - Handle naming conflicts with prefix/suffix/override strategies - **Dynamic Loading** - Tools appear as servers start - **Unified Interface** - Single API to access all tools ### Protocol Translation - **STDIO ↔ SSE** - Translate between different transport protocols - **Transparent Bridging** - No changes needed to existing servers - **Bidirectional** - Full request/response support - **Multiple Translators** - Run many translators simultaneously ### Monitoring & Observability - **Real-Time Metrics** - CPU, memory, request rates, and latency - **Structured Logging** - JSON logs with correlation IDs - **Health Checks** - Continuous monitoring of server health - **Prometheus Integration** - Export metrics for Prometheus - **WebSocket Streaming** - Live log and metric updates ### Security - **Token Authentication** - Secure API access - **CORS Support** - Configurable origin policies - **Rate Limiting** - Prevent abuse - **Input Validation** - Comprehensive request validation - **Non-root Containers** - Run as unprivileged user ## 🛠️ Configuration Create `mcp_compose.toml`: ```toml [composer] name = "my-composer" conflict_resolution = "prefix" [[servers]] name = "filesystem" command = "python" args = ["-m", "mcp_server_filesystem", "/data"] transport = "stdio" auto_start = true [[servers]] name = "calculator" command = "python" args = ["-m", "mcp_server_calculator"] transport = "stdio" auto_start = true [logging] level = "INFO" format = "json" [security] auth_enabled = true cors_origins = ["http://localhost:3000"] ``` See [User Guide](docs/USER_GUIDE.md) for complete configuration options. ### Proxied Server Types MCP Compose supports proxying to different types of MCP servers: #### STDIO Proxied Servers Proxy to local MCP servers running as subprocesses: ```toml [[servers.proxied.stdio]] name = "calculator" command = ["python", "mcp1.py"] restart_policy = "on_failure" max_restarts = 3 ``` #### SSE Proxied Servers Proxy to remote MCP servers using Server-Sent Events: ```toml [[servers.proxied.sse]] name = "remote-server" url = "http://localhost:8080/sse" auth_token = "your-token" auth_type = "bearer" timeout = 30 reconnect_on_failure = true # Auto-start the server as subprocess (optional) auto_start = true command = ["python", "mcp_server.py"] startup_delay = 3 ``` #### HTTP Proxied Servers Proxy to remote MCP servers using HTTP streaming: ```toml [[servers.proxied.http]] name = "http-server" url = "http://localhost:8080" protocol = "lines" # or "streamable-http" auth_token = "your-token" auth_type = "bearer" timeout = 30 ``` #### Streamable HTTP Proxied Servers Proxy to remote MCP servers using the native MCP Streamable HTTP protocol: ```toml [[servers.proxied.streamable-http]] name = "streamable-server" url = "http://localhost:8080/mcp" auth_token = "your-token" auth_type = "bearer" timeout = 30 reconnect_on_failure = true max_reconnect_attempts = 10 health_check_enabled = false # Auto-start the server as subprocess (optional) auto_start = true command = ["python", "mcp_server.py"] startup_delay = 3 ``` **Benefits of Streamable HTTP:** - Native MCP protocol support with bidirectional streaming - Better performance than traditional HTTP streaming - Full support for all MCP features (tools, resources, prompts) - Automatic session management See the [proxy-streamable-http example](examples/proxy-streamable-http/) for a complete working example. ## 🔌 REST API ### Key Endpoints ```bash # Health & Status GET /api/v1/health GET /api/v1/version GET /api/v1/status GET /api/v1/status/composition # Server Management GET /api/v1/servers POST /api/v1/servers/{id}/start POST /api/v1/servers/{id}/stop POST /api/v1/servers/{id}/restart # Tool Management GET /api/v1/tools POST /api/v1/tools/{name}/invoke # Configuration GET /api/v1/config PUT /api/v1/config POST /api/v1/config/validate POST /api/v1/config/reload # Translators GET /api/v1/translators POST /api/v1/translators DELETE /api/v1/translators/{id} # WebSocket WS /ws/logs WS /ws/metrics ``` See [API Reference](docs/API_REFERENCE.md) for complete documentation. ## 🧪 Testing ```bash # Run all tests make test # Run with coverage make test-coverage # Run specific test pytest tests/test_composer.py -v # Type checking make type-check # Linting make lint ``` ## 📦 Development ```bash # Clone repository git clone https://github.com/datalayer/mcp-compose.git cd mcp-compose # Install development dependencies pip install -e ".[dev]" # Install UI dependencies cd ui npm install npm run dev # Run tests make test # Build UI make build-ui # Run server mcp-compose serve ``` ## 🐳 Docker Deployment ### Quick Start ```bash # Build and run docker-compose up -d # View logs docker-compose logs -f # Stop docker-compose down ``` ### Production Deployment ```bash # Build with production settings docker build -t mcp-compose:prod . # Run with environment variables docker run -d \ -p 8000:8000 \ -v $(pwd)/config.toml:/app/config.toml:ro \ -e MCP_COMPOSER_AUTH_TOKEN=secret \ --name mcp-compose \ mcp-compose:prod ``` See [Deployment Guide](docs/DEPLOYMENT.md) for Kubernetes and production setup. ## 📚 Examples ### Git + File MCP Servers A complete example demonstrating how to orchestrate Git and Filesystem MCP servers with anonymous access. **Location:** [`examples/git-file/`](examples/git-file/) **Features:** - Git operations (status, log, diff, commit) - Filesystem operations (read, write, list) - Unified API with tool prefixing - No authentication required - Full Makefile for easy management **Quick Start:** ```bash cd examples/git-file make install make start make open-ui ``` See the [Git-File Example README](examples/git-file/README.md) for complete documentation. ### OAuth Authentication Example Production-ready example with GitHub OAuth2 authentication. **Location:** [`references/oauth/`](references/oauth/) **Features:** - OAuth2 authentication flow - JWT tokens - Protected MCP server endpoints - Pydantic AI agent integration See the [MCP Auth Example README](references/oauth/README.md) for details. ## 🗂️ Resources Configuration files and infrastructure resources are located in the [`resources/`](resources/) directory: - `nginx.conf` - Nginx reverse proxy configuration - `prometheus.yml` - Prometheus metrics collection - `grafana/` - Grafana dashboards and datasources ## 📊 Project Status ### Phase 4: Complete ✅ **Week 13-16 Deliverables:** - ✅ Modern React-based Web UI with 8 pages - ✅ Real-time monitoring dashboard - ✅ Log viewer with streaming - ✅ Metrics visualization with Recharts - ✅ Protocol translator management - ✅ Settings and preferences - ✅ Comprehensive documentation - ✅ Docker deployment setup - ✅ Production-ready configuration **Test Coverage:** 95% (265+ tests) **Code Quality:** Type-checked with mypy **Lines of Code:** ~15,000 (including UI) ## 🗺️ Roadmap ### Completed - ✅ Core composition engine - ✅ CLI interface - ✅ REST API (32 endpoints) - ✅ Web UI (8 pages) - ✅ Real-time monitoring - ✅ Protocol translation - ✅ Docker deployment - ✅ Comprehensive documentation ### Future Enhancements - 🔄 Plugin system for custom extensions - 🔄 GraphQL API support - 🔄 Advanced caching strategies - 🔄 Distributed deployment support - 🔄 Enhanced analytics - 🔄 CLI auto-completion ## 🤝 Contributing Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ```bash # Fork and clone git clone https://github.com/YOUR_USERNAME/mcp-compose.git # Create feature branch git checkout -b feature/amazing-feature # Make changes and test make test # Commit and push git commit -m "Add amazing feature" git push origin feature/amazing-feature # Create Pull Request ``` ## 📄 License BSD 3-Clause License - see [LICENSE](LICENSE) for details. ## 🙏 Acknowledgments - Built on [FastMCP](https://github.com/jlowin/fastmcp) framework - Inspired by the Model Context Protocol specification - UI built with React, TypeScript, and Recharts - Special thanks to all contributors ## 📧 Support - **Documentation**: [Full documentation](docs/) - **Issues**: [GitHub Issues](https://github.com/datalayer/mcp-compose/issues) - **Discussions**: [GitHub Discussions](https://github.com/datalayer/mcp-compose/discussions) - **Sponsor**: [Become a sponsor](https://github.com/sponsors/datalayer) --- Made with ❤️ by [Datalayer](https://datalayer.ai) composer = MCPServerComposer( composed_server_name="unified-data-server", conflict_resolution=ConflictResolution.PREFIX ) # Compose from current directory's pyproject.toml unified_server = composer.compose_from_pyproject() # Get detailed composition information summary = composer.get_composition_summary() print(f"Created server with {summary['total_tools']} tools") ``` #### Advanced Configuration ```python from pathlib import Path from mcp_compose import MCPServerComposer, ConflictResolution # Specify custom pyproject.toml location composer = MCPServerComposer( composed_server_name="my-server", conflict_resolution=ConflictResolution.SUFFIX ) # Compose with filtering unified_server = composer.compose_from_pyproject( pyproject_path=Path("custom/pyproject.toml"), include_servers=["jupyter-mcp-server", "earthdata-mcp-server"], exclude_servers=["deprecated-server"] ) # Access composed tools and prompts tools = composer.list_tools() prompts = composer.list_prompts() source_info = composer.get_source_info() print(f"Tools: {', '.join(tools)}") print(f"Sources: {', '.join(source_info.keys())}") ``` #### Discovery Only ```python from mcp_compose import MCPServerDiscovery # Discover MCP servers without composing discovery = MCPServerDiscovery() servers = discovery.discover_from_pyproject("pyproject.toml") for name, info in servers.items(): print(f"{name}: {len(info.tools)} tools, {len(info.prompts)} prompts") ``` ## Configuration ### Conflict Resolution Strategies When multiple servers provide tools or prompts with the same name, you can choose how to resolve conflicts: - **PREFIX** (default): Add server name as prefix (`server1_tool_name`) - **SUFFIX**: Add server name as suffix (`tool_name_server1`) - **OVERRIDE**: Last server wins (overwrites previous) - **IGNORE**: Skip conflicting items - **ERROR**: Raise an error on conflicts ### Example Conflict Resolution ```python # If two servers both have a "search" tool: # PREFIX: jupyter_mcp_server_search, earthdata_mcp_server_search # SUFFIX: search_jupyter_mcp_server, search_earthdata_mcp_server # OVERRIDE: Only the last server's "search" tool is kept ``` ## Real-World Examples ### Data Science Workflow Create a unified MCP server combining Jupyter notebook capabilities with Earth science data access: ```toml # pyproject.toml [project] dependencies = [ "jupyter-mcp-server>=1.0.0", "earthdata-mcp-server>=0.1.0", "weather-mcp-server>=2.0.0" ] ``` ```bash # Discover available tools python -m mcp_compose discover # Create unified server for data science workflow python -m mcp_compose compose \ --name "data-science-server" \ --conflict-resolution prefix \ --output unified_server.py ``` This creates a server with tools like: - `jupyter_create_notebook` - Create analysis notebooks - `earthdata_search_datasets` - Find Earth science data - `weather_get_forecast` - Access weather data - Combined prompts for data analysis workflows ### Development Environment Combine development tools and documentation servers: ```python from mcp_compose import MCPServerComposer, ConflictResolution composer = MCPServerComposer( composed_server_name="dev-environment", conflict_resolution=ConflictResolution.PREFIX ) # Compose development-focused servers dev_server = composer.compose_from_pyproject( include_servers=[ "code-review-mcp-server", "documentation-mcp-server", "testing-mcp-server" ] ) # Access all development tools in one place print("Available tools:", composer.list_tools()) ``` ### Custom Integration ```python from mcp_compose import MCPServerComposer from my_custom_server import MyMCPServer # Create composer composer = MCPServerComposer() # Compose discovered servers unified_server = composer.compose_from_pyproject() # Add your custom server manually if needed composer.add_server("custom", MyMCPServer()) # Get final composition summary summary = composer.get_composition_summary() print(f"Final server has {summary['total_tools']} tools from {summary['source_servers']} sources") ``` ## Project Structure When using MCP Compose, structure your project like this: ``` my-project/ ├── pyproject.toml # Define MCP server dependencies ├── src/ │ └── my_project/ │ ├── __init__.py │ └── main.py # Use composed server ├── composed_server.py # Generated unified server (optional) └── README.md ``` ### Sample pyproject.toml ```toml [project] name = "my-data-project" dependencies = [ "jupyter-mcp-server>=1.0.0", "earthdata-mcp-server>=0.1.0", "fastmcp>=1.2.0" ] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "mcp-compose>=1.0.0" ] ``` ## Error Handling The library provides comprehensive error handling: ```python from mcp_compose import MCPServerComposer, MCPComposerError, MCPDiscoveryError try: composer = MCPServerComposer() server = composer.compose_from_pyproject() except MCPDiscoveryError as e: print(f"Discovery failed: {e}") print(f"Search paths: {e.search_paths}") except MCPComposerError as e: print(f"Composition failed: {e}") print(f"Server count: {e.server_count}") ``` ## Troubleshooting ### Common Issues 1. **No MCP servers found**: Ensure your dependencies include packages with "mcp" in the name 2. **Import errors**: Check that MCP server packages are properly installed 3. **Naming conflicts**: Use appropriate conflict resolution strategy 4. **Missing tools**: Verify that server packages export an `app` variable ### Debug Mode ```bash # Enable verbose logging python -m mcp_compose discover --verbose # Check specific package python -c " from mcp_compose import MCPServerDiscovery discovery = MCPServerDiscovery() result = discovery._analyze_mcp_server('your-package-name') print(result) " ``` ``` ## API Reference ### MCPServerComposer Main class for composing MCP servers: ```python MCPServerComposer( composed_server_name: str = "composed-mcp-server", conflict_resolution: ConflictResolution = ConflictResolution.PREFIX ) ``` **Methods:** - `compose_from_pyproject(pyproject_path, include_servers, exclude_servers)` - Compose servers from dependencies - `get_composition_summary()` - Get summary of composition results - `list_tools()` - List all available tools - `list_prompts()` - List all available prompts - `get_source_info()` - Get mapping of tools/prompts to source servers ### MCPServerDiscovery Class for discovering MCP servers: ```python MCPServerDiscovery(mcp_server_patterns: List[str] = None) ``` **Methods:** - `discover_from_pyproject(pyproject_path)` - Discover servers from pyproject.toml - `get_package_version(dependency_spec)` - Extract version from dependency string ### ConflictResolution Enum for conflict resolution strategies: - `PREFIX` - Add server name as prefix - `SUFFIX` - Add server name as suffix - `OVERRIDE` - Last server wins - `IGNORE` - Skip conflicting items - `ERROR` - Raise error on conflicts ## Requirements - Python 3.8+ - FastMCP >= 1.2.0 - TOML parsing support ## Contributing We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details. 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes and add tests 4. Ensure all tests pass (`pytest`) 5. Commit your changes (`git commit -m 'Add amazing feature'`) 6. Push to the branch (`git push origin feature/amazing-feature`) 7. Open a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Changelog See [CHANGELOG.md](CHANGELOG.md) for version history and changes. ## Support - 📖 **Documentation**: Full API documentation and examples in this README - 🐛 **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/datalayer/mcp-compose/issues) - 💬 **Discussions**: Join the conversation in [GitHub Discussions](https://github.com/datalayer/mcp-compose/discussions) ## Related Projects - [FastMCP](https://github.com/modelcontextprotocol/python-sdk) - Python SDK for Model Context Protocol - [MCP Specification](https://spec.modelcontextprotocol.io/) - Official MCP specification - [Jupyter MCP Server](https://github.com/datalayer/jupyter-mcp-server) - MCP server for Jupyter functionality - [Earthdata MCP Server](https://github.com/datalayer/earthdata-mcp-server) - MCP server for NASA Earthdata access --- **Made with ❤️ by the Datalayer team** - [Earthdata MCP Server](https://github.com/your-org/earthdata-mcp-server) - MCP server for NASA Earthdata ## Changelog See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes. ## Support - GitHub Issues: [Report bugs or request features](https://github.com/your-org/mcp-compose/issues) - Documentation: [Full documentation](https://your-org.github.io/mcp-compose/) - Community: [Join the discussion](https://github.com/your-org/mcp-compose/discussions)