<!-- ~ Copyright (c) 2023-2024 Datalayer, Inc. ~ ~ BSD 3-Clause License -->

✨ MCP Compose

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

# 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)

# 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

# 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

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:

[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 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:

[[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:

[[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:

[[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:

[[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 for a complete working example.

🔌 REST API

Key Endpoints

# 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 for complete documentation.

🧪 Testing

# 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

# 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

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Production Deployment

# 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 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/

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:

cd examples/git-file
make install
make start
make open-ui

See the Git-File Example README for complete documentation.

OAuth Authentication Example

Production-ready example with GitHub OAuth2 authentication.

Location: references/oauth/

Features:

• OAuth2 authentication flow
• JWT tokens
• Protected MCP server endpoints
• Pydantic AI agent integration

See the MCP Auth Example README for details.

🗂️ Resources

Configuration files and infrastructure resources are located in the 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 for details.

# 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 for details.

🙏 Acknowledgments

• Built on 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
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Sponsor: Become a sponsor

Made with ❤️ by Datalayer 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

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

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

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:

pyproject.toml

[project] dependencies = [ "jupyter-mcp-server>=1.0.0", "earthdata-mcp-server>=0.1.0", "weather-mcp-server>=2.0.0" ]

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:

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

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

[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:

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

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:

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:

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 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 file for details.

Changelog

See 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
• 💬 Discussions: Join the conversation in GitHub Discussions

Related Projects

• FastMCP - Python SDK for Model Context Protocol
• MCP Specification - Official MCP specification
• Jupyter MCP Server - MCP server for Jupyter functionality
• Earthdata MCP Server - MCP server for NASA Earthdata access

Made with ❤️ by the Datalayer team

• Earthdata MCP Server - MCP server for NASA Earthdata

Changelog

See CHANGELOG.md for a detailed history of changes.

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation
• Community: Join the discussion