MetaMCP: a self-hosted gateway that merges MCP servers behind one endpoint
MCP Aggregator, Orchestrator, Middleware, Gateway in one docker
At a glance
- What is it?
- MetaMCP (metatool-ai/metamcp) is a TypeScript MCP proxy that aggregates STDIO and HTTP MCP servers into namespaces, exposes them as SSE or Streamable HTTP endpoints, and applies middleware. The README confirms the architecture and the Docker Compose path; it also flags the ai-dev branch as pre-release and lists several features as coming soon.
- Who is it for?
- Adopt MetaMCP if you run several MCP servers and want one authenticated endpoint per group of tools, and you are willing to run Postgres and the app yourself. Do not adopt it if you need a finished middleware library, since the README labels observability middleware and the Elasticsearch-style tool selection as coming soon.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- No. The owners have archived the repository on GitHub, so it is read-only and no longer receives changes.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- metatool-ai/metamcp2,761 ★ · +107
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| metatool-ai/metamcp | 2.7k | 2.8k |
107 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem: MCP clients connect to one server at a time
An MCP client such as Cursor or Claude Desktop is configured with a list of servers, and each server is a separate process or URL with its own tool set. As that list grows, three things get harder. You repeat credentials in every client config. You cannot hand a colleague or an agent a single URL that represents a curated subset of tools. And there is nowhere to put shared behaviour, such as rate limits, between the client and the upstream servers. MetaMCP takes the position that this belongs in infrastructure rather than in each client. The README describes it as a proxy that dynamically aggregates MCP servers into a unified MCP server and applies middlewares, and notes that MetaMCP is itself an MCP server, so it plugs into any MCP client. The stated audience is developers who use it as infrastructure to host dynamically composed MCP servers through a unified endpoint and build agents on top. The use cases list is concrete: group servers into namespaces, host them as meta-MCPs, assign public SSE or Streamable HTTP endpoints with auth, and switch a namespace for an endpoint in one click.
Namespaces, endpoints and the STDIO config format
The core abstraction is the namespace: a named group of upstream MCP servers. An endpoint is the public surface that exposes a namespace with authentication, over SSE or Streamable HTTP. Upstream servers are declared in JSON, and the README gives this example: a key named HackerNews with type STDIO, command uvx, and args ["mcp-hn"]. That shape is the whole model for a local process server. For STDIO servers the README states there are three ways to handle environment variables and secrets, and the first is raw values, described as direct string values that are not recommended. The material is truncated at that point, so the other two modes cannot be described here with confidence. The middleware concept is listed as a first-class part of the product, but the README marks pluggable middleware around observability and security as coming soon, which means the aggregation and endpoint layer is the part you can rely on today. Tool overrides and annotations, an inspector, and environment variable handling round out the concept list, and the inspector is described as usable in-house to check whether a MetaMCP endpoint works.
Getting it running with Docker Compose
The recommended path in the README is Docker Compose, listed before the Dev Containers and local development options. The project publishes a container image to GitHub Container Registry, and the README links the package page under ghcr.io for metatool-ai/metamcp. The repository also ships a metamcp.svg diagram and a screenshot, so the intended shape of a deployment is visible without reading source. Beyond Compose, the README documents a custom Dockerfile path tied to the cold start problem: STDIO servers must be started before they can answer, and the README treats that latency as a known issue with its own section. That is the practical detail most people miss. If your namespace contains several STDIO servers, the first request after a restart pays for process startup. The README also documents log levels and authentication as separate sections, and an API key auth troubleshooting section, which suggests API key handling is the part users get wrong most often. For clients that only speak STDIO, such as Claude Desktop, the README has a dedicated section on connecting them, which implies a bridge step rather than a direct URL. None of these commands are reproduced here as verified output; the README is the source for each.
Auth, OIDC and registration controls
MetaMCP ships more access control than a typical side project. The README documents an OpenID Connect provider section with configuration, a list of supported providers, security features and usage notes. It also documents registration controls with available controls and enterprise use cases, which points at the scenario where an operator runs one MetaMCP instance for a team and needs to decide who can create accounts and namespaces. Rate limiting is documented under traffic management as MCP rate limit. The combination matters because an endpoint exposed over SSE or Streamable HTTP is reachable by anything that can hold the URL, and the upstream servers behind it may hold real credentials. The README's separate API key auth troubleshooting section is a signal that misconfiguration here is common enough to warrant its own heading. The README says raw values are not recommended, which implies an alternative exists, but the truncated text does not let me describe it. Treat secret storage as something to confirm in the docs site before you put production credentials behind a namespace.
Where MetaMCP is the wrong tool
If you connect to one or two MCP servers and your client config is stable, MetaMCP adds a Postgres-backed service, an auth layer and a network hop for no benefit. The aggregation only pays off when the number of servers or the number of consumers grows. The second limitation is maturity of the middleware layer. The README explicitly marks pluggable middleware around observability and security as coming soon, and lists Elasticsearch-style tool selection for MCP tools as coming soon too. So the pitch in the repository description, middleware and orchestration in one docker, describes a product whose middleware surface is still being built. Third, branch discipline. The README states that the ai-dev branch is the forward ongoing dev branch containing AI agent changes, and asks you to test before building an image from that branch. The release list shows 2.4.x versions, with v2.4.22 noting security updates, custom headers and tool sync caching. Anyone who builds from the default branch without reading that warning is running pre-release code. Fourth, the README itself acknowledges maintenance delay from the author, and points to a community maintained fork at Umbrella-IT-Group/metamcp. That is an honest signal about review bandwidth.
Alternatives and the difference in approach
The most direct comparison is the community fork the README links, Umbrella-IT-Group/metamcp. The difference is governance rather than design: the upstream README describes the author merging community PRs and adding AI changes on the ai-dev branch, while the fork is maintained by a separate group. If your concern is release cadence and you want a maintainer who is not also running an experimental branch, the fork is the thing to evaluate, and you should diff the two before committing. A second alternative is not running an aggregator at all: configure each MCP server directly in each client. That keeps zero additional infrastructure and no shared secret store, at the cost of duplicating configuration and losing per-endpoint auth. A third option is writing a thin MCP server of your own that re-exports the tools you want. That gives you exact control over which tools are visible and how they are named, but you now own tool schema drift every time an upstream server changes its interface. MetaMCP's namespace and tool override model exists precisely to avoid that maintenance, which is the honest trade: less code to own, more infrastructure to operate.
Maintenance, licence and what to check before adopting
MetaMCP is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and the README states it plainly. This is not legal advice; if you redistribute the software or embed it in a product, read the licence text and your own obligations. On maintenance cost, the release history runs through 2.4.x, with v2.4.22 in December 2025 carrying security updates, custom headers and tool sync caching, and a last push in June 2026. The README also carries an author note about recent maintenance delay and a commitment to keep merging PRs. For an operator, the practical costs are Postgres, the container, and the upgrade path between 2.4.x releases. The custom Dockerfile section exists because of cold start, so plan to own that file if your namespaces include STDIO servers. Before adopting, verify three things in the docs site: how the two non-raw secret storage modes work, whether your identity provider is in the supported OIDC list, and whether the middleware you need has left the coming soon state. The last one determines whether MetaMCP is a gateway or a gateway plus a policy layer.
Editorial conclusion
Adopt MetaMCP if you run several MCP servers and want one authenticated endpoint per group of tools, and you are willing to run Postgres and the app yourself. Do not adopt it if you need a finished middleware library, since the README labels observability middleware and the Elasticsearch-style tool selection as coming soon. Before deploying, verify which branch you are building from: the README states the ai-dev branch carries ongoing agent changes and asks you to test before building an image from it, while the release list is on 2.4.x.
Frequently asked questions
What is MetaMCP?
It is an MCP proxy that aggregates MCP servers into one unified MCP server and applies middlewares, so it can itself be plugged into any MCP client. Servers are grouped into namespaces, namespaces are exposed through endpoints, and an endpoint carries the transport and the authentication choice.
Which branch do I get when I clone MetaMCP, and what does it say about itself?
The default branch is ai-dev, described as the forward ongoing development branch containing AI agent changes, with a request to test before building an image from it. The same notice mentions the review backlog and points at a community maintained fork.
What credentials does the MetaMCP compose file default to?
The Postgres user, database, host and port all carry defaults, and the password defaults to m3t4mcp while BETTER_AUTH_SECRET defaults to the literal string your-super-secret-key-change-this-in-production. DATABASE_URL is composed from whichever values apply, so an unset environment produces a known password.
How does MetaMCP pass secrets to STDIO MCP servers?
Three ways: raw values in the config, which the guide marks as not recommended for secrets; references written as ${VAR_NAME} and resolved from the container environment at runtime; and automatic pass-through, where a variable can be omitted entirely if the container already holds a matching name.
Which authentication options does a MetaMCP endpoint support?
An API key, placed in a header or in a query parameter, or standard OAuth as specified in MCP Spec 2025-06-18. Endpoints are served over SSE or Streamable HTTP, with OpenAPI endpoints also available for clients that expect that shape.
Is there a released MetaMCP version for the code on the default branch?
Not for the recent part of it. The newest listed release is 2.4.22 from 19 December 2025, and the branch has commits dated 22 June 2026. Anything built from the branch is therefore ahead of the last tag, and anything installed from a tag is behind the branch.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/metatool-ai-metamcp)Star history chart for your README
[](https://hysenlabs.com/projects/metatool-ai-metamcp)Was this useful?