metamcp

MetaMCP (Meta MCP) is an MCP server that acts as an aggregator, orchestrator, middleware gateway, and inspector for multiple MCP servers. It lets you group one or more MCP servers into namespaces, host them under unified endpoints, and apply pluggable middleware for observability, security, and routing. As a central MCP hub, MetaMCP can expose combined endpoints (SSE or Streamable HTTP) that aggregate the underlying MCP servers, enabling consistent access control and tooling across multiple backends. Developers can remix and compose MCP servers on the fly, enabling a flexible, modular MCP infrastructure without modifying each individual server.

To use MetaMCP, run the server and point it at your underlying MCP services. MetaMCP will discover, group, and expose them through configured endpoints. You can leverage middleware to enforce authentication, logging, rate limiting, or custom annotations per namespace. The project also provides an inspector-like capability to save server configurations, inspect endpoints, and experiment with tool selections within a unified UI or API.

Prerequisites:

• Docker and Docker Compose (recommended) or a Python/uvx setup if you prefer running STDIO-based servers directly.
• Access to the MetaMCP repository and any MCP servers you plan to aggregate.

Option A: Run with Docker Compose (recommended)

1. Clone the repository and navigate to the project directory.
2. Ensure Docker is running.
3. Use the provided docker-compose.yml (adjust environment variables as needed) to start MetaMCP along with your MCP services.

Example (conceptual, adapt to your environment):

# 1) Clone the repo
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp

# 2) Copy example env and config if provided
cp .env.example .env

# 3) Start services
docker-compose up -d

Option B: Local development / development container

1. Install prerequisites (Node/Python as needed by your environment).
2. If you have a dev container setup, follow the Dev Containers instructions in the repo to open a ready-to-run environment in VSCode.
3. Start MetaMCP with the development script or dockerized development flow described in the repository.

Option C: STDIO/uvx-based local run (manual)

1. Ensure Python/uv tooling is available and the metamcp package is accessible.
2. Start the STDIO MCP server alongside MetaMCP by referencing the appropriate command in mcp_config (see example).
3. Verify endpoints and namespace configurations are loaded correctly.

Tips and notes:

• If you use STDIO MCP servers, you can specify environment variables in your mcp.json using direct values, ${ENV_VAR} references, or rely on auto-matching where possible. Secret values should not be committed to git; use environment variable references instead.
• When running in development, add globalEnv entries to turbo.json (or equivalent) to ensure environment variables are passed through to running processes.
• MetaMCP supports multiple deployment modes (Docker, Docker Compose, STDIO). Choose the mode that best fits your workflow and CI/CD setup.
• If you encounter authentication or endpoint issues, verify namespace configuration and middleware wiring, as these are common sources of misrouting in a multi-server setup.