# Add to your Claude Code skills
git clone https://github.com/metatool-ai/metamcp
README.md
๐ MetaMCP (MCP Aggregator, Orchestrator, Middleware, Gateway in one docker)
๐ข 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
๐ท๏ธ 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.
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 in turbo.json under globalEnv to be passed to the development processes. This is not required for production Docker deployments.
๐ท๏ธ 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
Override tool names/titles/descriptions per namespace and attach custom MCP annotations (e.g. { "annotations": { "readOnlyHint": false } })
๐ 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 between API-Key Auth (in header or query param) or standard OAuth in MCP Spec 2025-06-18
Host through SSE or Streamable HTTP transports in MCP and OpenAPI endpoints for clients like Open WebUI
โ๏ธ Middleware
Intercepts and transforms MCP requests and responses at namespace level
Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.
โ๏ธ Tool Overrides & Annotations
Open a namespace โ Tools tab to see every tool coming from connected MCP servers.
Each saved tool can be expanded and edited inline: update the display name/title/description or provide a JSON blob with namespace-specific annotations (for example { "annotations": { "readOnlyHint": false } }).
Badges in the table ("Overridden", "Annotations") show which tools currently have custom metadata. Hover them to read a tooltip describing what was overridden.
Annotation overrides are merged with whatever the upstream MCP server returns, so you can safely add custom UI hints without losing provider metadata.
๐ 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
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
๐ฆ Build development environment with Dev Containers (VSCode/Cursor)
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.