MCP Aggregator, Orchestrator, Middleware, Gateway in one docker
MCP Aggregator, Orchestrator, Middleware, Gateway in one docker
** Latest Update:** This ai-dev branch will be the forward onging dev branch which contains ai agent changes. Please test before you build the image based on this branch. There has been many PRs thanks to the community but merging and reviewing them has been a growing effort too. I decided to include ai changes. At least so far the core functionality works. There is also a community maintained fork (ty a lot!): https://github.com/Umbrella-IT-Group/metamcp
** Update:** [From the author: apologize for some recent maintainence delay, but will at least keep merging PRs, more background here]
MetaMCP is a MCP proxy that lets you dynamically aggregate MCP servers into a unified MCP server, and apply middlewares. MetaMCP itself is a MCP server so it can be easily plugged into ANY MCP clients.
For more details, consider visiting our documentation site: https://docs.metamcp.com
English | 简体中文
Generally developers can use MetaMCP as infrastructure to host dynamically composed MCP servers through a unified endpoint, and build agents on top of it.
Quick demo video: https://youtu.be/Cf6jVd2saAs
A MCP server configuration that tells MetaMCP how to start a MCP server.
"HackerNews": {
"type": "STDIO",
"command": "uvx",
"args": ["mcp-hn"]
}
For STDIO MCP servers, MetaMCP supports three ways to handle environment variables and secrets:
1. Raw Values - Direct string values (not recommended for secrets):
API_KEY=your-actual-api-key-here
DEBUG=true
2. Environment Variable References - Use ${ENV_VAR_NAME} syntax:
API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}
3. Auto-matching - If the expected environment variable name in your tool matches the container's environment variable, you can omit it entirely. MetaMCP will automatically pass through matching environment variables.
** Security Note**: Environment variable references (
${VAR_NAME}) are resolved from the MetaMCP container's environment at runtime. This keeps actual secret values out of your configuration and git repository.
⚙️ Development Note: For local development with
pnpm run dev:docker, ensure your environment variables are listed inturbo.jsonunderglobalEnvto be passed to the development processes. This is not required for production Docker deployments.
{ "annotations": { "readOnlyHint": false } })Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.
{ "annotations": { "readOnlyHint": false } }).Clone repo, prepare .env, and start with docker compose:
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d
If you modify APP_URL env vars, make sure you only access from the APP_URL, because MetaMCP enforces CORS policy on the URL, so no other URL is accessible.
Note that the pg volume name may collide with your other pg dockers, which is global, consider rename it in docker-compose.yml:
volumes:
metamcp_postgres_data:
driver: local
You can use the VSCode/Cursor extension to build the development environment in a container.
It only requires that you have an environment running Docker or a similar alternative (the docker/docker compose command is required), and no other dependent components need to be installed on your host machine.
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
code .
Dev Containers: Reopen in Container.VSCode will open the Dev Containers project in a new window, where it will build the runtime and install the toolchain according to the Dockerfile before starting the connection and finally installing the MetaMCP dependencies.
note This process requires a reliable network connection, and it will access Docker Hub, GitHub, and some other sites. You will need to ensure the network connection yourself, otherwise the container build may fail.
Wait some minutes, depending on the internet connection or computer performance, it may take from a few minutes to tens of minutes, you can click on the Progress Bar in the bottom right corner to view a live log where you will be able to check unusual stuck.
After finished, you can run pnpm dev to start the development server.
Still recommend running postgres through docker for easy setup:
pnpm install
pnpm dev
If you have questions, feel free to leave GitHub issues or PRs.
Example mcp.json
{
"mcpServers": {
"MetaMCP": {
"url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
}
}
}
Since MetaMCP endpoints are remote only (SSE, Streamable HTTP, OpenAPI), clients that only support stdio servers (like Claude Desktop) need a local proxy to connect.
Note: While mcp-remote is sometimes suggested for this purpose, it's designed for OAuth-based authentication and doesn't work with MetaMCP's API key authentication. Based on testing, mcp-proxy is the recommended solution.
Here's a working configuration for Claude Desktop using mcp-proxy:
Using Streamable HTTP
{
"mcpServers": {
"MetaMCP": {
"command": "uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
],
"env": {
"API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
}
}
}
}
Using SSE
{
"mcpServers": {
"ehn": {
"command": "uvx",
"args": [
"mcp-proxy",
"http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
],
"env": {
"API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
}
}
}
}
Important notes:
<YOUR_ENDPOINT_NAME> with your actual endpoint name<YOUR_API_KEY_HERE> with your MetaMCP API key (format: sk_mt_...)For more details and alternative approaches, see issue #76.
?api_key= param api key auth doesn't work for SSE. It only works for Streamable HTTP and OpenAPI.Authorization: Bearer <API_KEY> header.uvx or npx, you need to customize the Dockerfile to install dependencies on your own.No open issues yet, or sync has not completed.