# Mcp Compose

> 🔧 Compose Model Context Protocol (MCP) servers with management capabilities, REST API, and Web UI - Similar to Docker Compose

- **Type:** MCP server
- **Install:** `agentstack add mcp-datalayer-mcp-compose`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [datalayer](https://agentstack.voostack.com/s/datalayer)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** BSD-3-Clause
- **Upstream author:** [datalayer](https://github.com/datalayer)
- **Source:** https://github.com/datalayer/mcp-compose
- **Website:** https://mcp-compose.datalayer.tech

## Install

```sh
agentstack add mcp-datalayer-mcp-compose
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-datalayer-mcp-compose
- Seller: https://agentstack.voostack.com/s/datalayer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.