MetaMCP: a self-hosted gateway that merges MCP servers behind one endpoint

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. What the material does not provide is a threat model or a statement about how upstream secrets are stored. 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 material shows a release history 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.

Official sources

1. License: MIT
2. metatool-ai/metamcp on GitHub
3. Project website
4. README
5. Releases