MetaMCP is a powerful 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.
- 🔄 One-click server switching - Save and switch MCP server configs for Claude Desktop, Cursor, or custom agents
- 🔍 Enhanced MCP inspector - Debug with saved server configurations
- 🔗 Unified server aggregation - Join multiple servers for simplified agent development
- ⚡ Dynamic tool management - Quick toggles to enable/disable servers and tools
- 🛠️ Middleware support - Apply logging, error handling, and custom transformations
- 🎯 Dynamic search rules - Apply search rules and return different toolsets for agent builders
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 --build -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
- 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: