🚀 MetaMCP (Aggregate MCP servers & apply middlewares; host & emit unified MCP servers out)

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.

📋 Table of Contents

• 🎯 Use Cases
• 📖 Concepts
  • 🖥️ MCP Server
  • 🏷️ MetaMCP Namespace
  • 🌐 MetaMCP Endpoint
  • ⚙️ Middleware
  • 🔍 Inspector
• 🚀 Quick Start
  • 🐳 Run with Docker Compose (Recommended)
  • 💻 Local Development
• 🔌 MCP Protocol Compatibility
• ❄️ Cold Start Problem and Custom Dockerfile
• 🔐 Authentication
• 🏗️ Architecture
  • 📊 Sequence Diagram
• 🗺️ Roadmap
• 🤝 Contributing
• 📄 License
• 🙏 Credits

🎯 Use Cases

• 🏷️ 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

📖 Concepts

🖥️ MCP Server

A MCP server configuration that tells MetaMCP how to start a MCP server.

"HackerNews": {
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-hn"]
}

🏷️ MetaMCP Namespace

• Group one or more MCP servers into a namespace
• Enable/disable MCP servers or at tool level
• Apply middlewares to MCP requests and responses

🌐 MetaMCP Endpoint

• 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

⚙️ Middleware

• 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

🔍 Inspector

Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.

🚀 Quick Start

🐳 Run with Docker Compose (Recommended)

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

💻 Local Development

Still recommend running postgres through docker for easy setup:

pnpm install
pnpm dev

🔌 MCP Protocol Compatibility

• ✅ 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.

❄️ Cold Start Problem and Custom Dockerfile

⚠️ Cold start issue for hosting 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.

🔐 Authentication

• 🛡️ 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.

SSE conf for Nginx

Since MCP leverages SSE for long connection, if you are using reverse proxy like nginx, please refer to an example setup nginx.conf.example

🏗️ Architecture

• 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

📊 Sequence Diagram

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

🗺️ Roadmap

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

🤝 Contributing

We welcome contributions! See details at CONTRIBUTING.md

📄 License

MIT

Would appreciate if you mentioned with back links if your projects use the code.

🙏 Credits

Some code inspired by:

• MCP Inspector
• MCP Proxy Server