Mcp Compose

[](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

# 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](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:

[[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](examples/proxy-streamable-http/) 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](docs/API_REFERENCE.md) 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](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:

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.

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

---

Made with ❤️ by Datalayer composer = MCPServerComposer( composedservername="unified-data-server", conflictresolution=ConflictResolution.PREFIX )

Compose from current directory's pyproject.toml

unifiedserver = composer.composefrom_pyproject()

Get detailed composition information

summary = composer.getcompositionsummary() 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 filteri

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [datalayer](https://github.com/datalayer)
- **Source:** [datalayer/mcp-compose](https://github.com/datalayer/mcp-compose)
- **License:** BSD-3-Clause
- **Homepage:** https://mcp-compose.datalayer.tech

Install and usage instructions live in the source repository linked above.