How do I install MCP Compose?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does MCP Compose need an API key?

No required environment variable is listed on this record.

What transport does MCP Compose use?

MCP Compose runs locally over stdio.

MCP Compose MCP server

Q: When was MCP Compose last checked?

Last checked 2026-10-28. 🔧 Compose Model Context Protocol (MCP) servers with management capabilities, REST API, and Web UI — Similar to Docker Compose

✨ 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 - Complete guide for using MCP Compose
API Reference - Full REST API and Python API documentation
Deployment Guide - Production deployment with Docker & Kubernetes
Architecture - 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

```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

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

No MCP servers found: Ensure your dependencies include packages with "mcp" in the name
Import errors: Check that MCP server packages are properly installed
Naming conflicts: Use appropriate conflict resolution strategy
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:

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

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.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and add tests
Ensure all tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install MCP Compose?

Does MCP Compose need an API key?

What transport does MCP Compose use?

When was MCP Compose last checked?

Documentation

✨ MCP Compose

🎯 Overview

Key Capabilities

🚀 Quick Start

Installation

Using Docker (Recommended)

Using CLI

Using Python API

🎨 Web UI Features

📖 Documentation

💡 What can you use MCP Compose for?

🏗️ Architecture

✨ Core Features

Server Management

✨ Core Features

Server Management

Tool & Prompt Composition

Protocol Translation

Monitoring & Observability

Security

🛠️ Configuration

Proxied Server Types

STDIO Proxied Servers

SSE Proxied Servers

HTTP Proxied Servers

Streamable HTTP Proxied Servers

🔌 REST API

Key Endpoints

🧪 Testing

📦 Development

🐳 Docker Deployment

Quick Start

Production Deployment

📚 Examples

Git + File MCP Servers

OAuth Authentication Example

🗂️ Resources

📊 Project Status

Phase 4: Complete ✅

🗺️ Roadmap

Completed

Future Enhancements

🤝 Contributing

📄 License

🙏 Acknowledgments

📧 Support

Compose from current directory's pyproject.toml

Get detailed composition information

Discovery Only

Configuration

Conflict Resolution Strategies

Example Conflict Resolution

Real-World Examples

Data Science Workflow

Development Environment

Custom Integration

Project Structure

Sample pyproject.toml

Error Handling

Troubleshooting

Common Issues

Debug Mode

MCPServerDiscovery

ConflictResolution

Requirements

Contributing

License

Changelog

Support

Related Projects