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.
- 🎯 Use Cases
- 📖 Concepts
- 🚀 Quick Start
- 🔌 MCP Protocol Compatibility
- ❄️ Cold Start Problem and Custom Dockerfile
- 🔐 Authentication
- 🏗️ Architecture
- 🗺️ Roadmap
- 🤝 Contributing
- 📄 License
- 🙏 Credits
- 🏷️ Group MCP servers into namespaces, host them as meta-MCPs, and assign public endpoints (SSE or Streamable HTTP), with auth. One-click to switch a namespace for an endpoint.
- 🎯 Pick tools you only need when remixing MCP servers. Apply other pluggable middleware around observability, security, etc. (coming soon)
- 🔍 Use as enhanced MCP inspector with saved server configs, and inspect your MetaMCP endpoints in house to see if it works or not.
- 🔍 Use as Elasticsearch for MCP tool selection (coming soon)
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"]
}- Group one or more MCP servers into a namespace
- Enable/disable MCP servers or at tool level
- Apply middlewares to MCP requests and responses
- Create endpoints and assign namespace to endpoints
- Multiple MCP servers in the namespace will be aggregated and emitted as a MetaMCP endpoint
- Choose auth level and strategy
- Host through SSE or Streamable HTTP transports
- Intercepts and transforms MCP requests and responses at namespace level
- Built-in example: "Filter inactive tools" - optimizes tool context for LLMs
- Future ideas: tool logging, error traces, validation, scanning
Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.
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 -dStill recommend running postgres through docker for easy setup:
pnpm install
pnpm dev- ✅ Tools, Resources, and Prompts supported
- ✅ OAuth-enabled MCP servers tested for 03-26 version
If you have questions, feel free to leave GitHub issues or PRs.
stdio type MCP servers:
- First run will be slow as package managers (uvx, npx) install dependencies
- Happens again on docker restart
🛠️ Solution: Customize the Dockerfile to add dependencies or pre-install packages to reduce cold start time.
- 🛡️ Better Auth for frontend and backend (trpc procedures)
- 🍪 Session cookies enforce internal MCP proxy connections
- 🔑 API key auth for external access via
Authorization: Bearer <api-key>header - Note though: the repo is not designed for multi-tenancy and each org should self-host an instance for org wide. E.g., MCP server has no user_id association, so every account have access to every MCP server configs hosted on the instance.
- Frontend: Next.js
- Backend: Express.js with tRPC, hosting MCPs through TS SDK and internal proxy
- Auth: Better Auth
- Structure: Standalone monorepo with Turborepo and Docker publishing
Note: Prompts and resources follow similar patterns to tools.
sequenceDiagram
participant MCPClient as MCP Client (e.g., Claude Desktop)
participant MetaMCP as MetaMCP Server
participant MCPServers as Installed MCP Servers
MCPClient ->> MetaMCP: Request list tools
loop For each listed MCP Server
MetaMCP ->> MCPServers: Request list_tools
MCPServers ->> MetaMCP: Return list of tools
end
MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
MetaMCP ->> MCPClient: Return aggregated list of tools
MCPClient ->> MetaMCP: Call tool
MetaMCP ->> MCPServers: call_tool to target MCP Server
MCPServers ->> MetaMCP: Return tool response
MetaMCP ->> MCPClient: Return tool response
Potential next steps:
- 🔌 Headless Admin API access
- 🔍 Dynamically apply search rules on MetaMCP endpoints
- 🛠️ More middlewares
- 💬 Chat/Agent Playground
- 🧪 Testing & Evaluation for MCP tool selection optimization
- ⚡ Dynamically generate MCP servers
We welcome contributions! See details at CONTRIBUTING.md
MIT
Would appreciate if you mentioned with back links if your projects use the code.
Some code inspired by: