# MetaMCP: a self-hosted MCP gateway for aggregating and remixing MCP servers

> MetaMCP is an MCP proxy that groups MCP servers into namespaces, exposes them as one meta-MCP endpoint, and hosts that endpoint behind auth. It is for teams that have outgrown pasting a dozen server entries into every client config.

**metatool-ai/metamcp** — MCP Aggregator, Orchestrator, Middleware, Gateway in one docker

- Repository: https://github.com/metatool-ai/metamcp
- Website: https://docs.metamcp.com
- Stars: 2,694 · Forks: 436
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/metatool-ai-metamcp

## The problem MetaMCP solves: MCP config sprawl

Every MCP client keeps its own list of servers. Add a fifth server and you edit the config in Cursor, then Claude Desktop, then whatever agent framework you are evaluating. The README frames the project as a proxy that "lets you dynamically aggregate MCP servers into a unified MCP server, and apply middlewares", and notes that MetaMCP is itself an MCP server, so it plugs into any MCP client. The intended audience is developers treating MCP as infrastructure: the use-case list leads with grouping servers into namespaces, hosting them as meta-MCPs, and assigning public endpoints with auth, with one-click switching of which namespace an endpoint serves. A second use case is tool selection, picking only the tools you need when remixing servers. That second one is where the design gets interesting, because a namespace is not just a rename of a server list. It is a curated surface. If your agent only needs three of the forty tools a server exposes, the namespace is where you express that, and every downstream client inherits the decision.

## Namespaces, endpoints and middlewares: how the aggregation works

The repository is a pnpm and Turbo monorepo: apps/frontend and apps/backend, plus packages/trpc, packages/zod-types and shared config packages. The backend holds the server definitions and the namespace logic; the frontend is the admin surface where you register MCP servers, build namespaces, and inspect endpoints. A server definition tells MetaMCP how to launch or reach an upstream. The README gives this STDIO example:

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

STDIO servers are spawned as child processes, and for those the README documents three ways to handle environment variables and secrets, beginning with raw string values in the config. Endpoints are the outward-facing part: the README describes assigning public endpoints over SSE or Streamable HTTP, with auth, and switching which namespace an endpoint serves. Middlewares sit between the aggregated servers and the endpoint; the README lists observability and security as the intended categories but marks pluggable middleware as coming soon, so treat the middleware story as incomplete rather than shipped. The Dockerfile reveals an operational detail worth knowing: after the build it patches Next.js proxy-request.js, replacing a 30000 value with 600000. That is a ten-minute timeout for proxied requests, applied by sed against a pinned Next.js path. It is a pragmatic fix for long-running MCP calls, and also a patch that will break or silently stop applying when the Next.js version moves.

## Installing MetaMCP with Docker Compose and connecting a client

The README recommends Docker Compose. The compose file pulls ghcr.io/metatool-ai/metamcp:latest, reads a .env file, and publishes port 12008. Postgres connection details default to host postgres, port 5432, user metamcp_user, database metamcp_db, and the DATABASE_URL is composed from those variables. APP_URL and NEXT_PUBLIC_APP_URL default to http://localhost:12008, and BETTER_AUTH_SECRET has a placeholder default that the file itself tells you to change in production. Bring it up with:

```bash
docker compose up -d
```

Then open http://localhost:12008 and create an account. The compose file also documents bootstrap configuration through a BOOTSTRAP_USERS variable, shown as a JSON array of objects with email, password and name fields, which is how you seed accounts without clicking through registration. Registration controls and OIDC provider support are both documented in the README if you need them. To connect a client, add MetaMCP as a server entry pointing at your endpoint. The README shows Cursor via mcp.json, and there is a separate section for Claude Desktop and other STDIO-only clients, which is the case where you need a bridge because those clients cannot speak HTTP directly. If auth fails, the README keeps an API key auth troubleshooting section; check it before assuming the container is broken.

## Cold starts, environment variables and the maintenance caveat

The README has a section titled "Cold Start Problem and Custom Dockerfile". That is an admission that spinning up STDIO servers on demand costs latency, and the suggested answer is building your own image rather than using the published one. For a gateway that fronts interactive clients, cold start is the difference between a tool call feeling instant and feeling stalled. The Dockerfile also shows the runtime base is the official uv image with Node.js 20 and pnpm installed on top, so the image is not small, and it exists to support Python-based MCP servers launched through uvx. On maintenance: the last push to the repository was on 2026-06-22, and the README carries an author note apologising for a maintenance delay while committing to keep merging PRs. The default branch is ai-dev, which the README describes as the forward ongoing development branch containing AI agent changes, with an explicit instruction to test before building an image from it. That is an unusual default. If you clone and build without thinking, you get the agent-changes branch, not the stable line, and the latest release listed is v2.4.22 from 2025-12-19. Pin a tag. The README also points to a community-maintained fork.

## Where MetaMCP is the wrong tool

If you run one MCP server for one client, MetaMCP adds a Postgres instance, a web admin, an auth layer and a container to your stack in exchange for nothing. The client config you already have is smaller and has fewer failure points. If your client cannot speak HTTP and you do not want to run a bridge, the STDIO-only path is documented but it is extra moving parts. If you need middleware today, check the README carefully: observability and security middleware are described as coming soon, so a namespace gives you aggregation and tool selection, not a filtering or policy engine. And if you need a stable API surface, the ai-dev default branch plus a release cadence that the README itself describes as straining under community PRs means you should read the release notes for the tag you pin rather than tracking the branch.

## MetaMCP compared with a plain MCP client config

The honest alternative is not another gateway; it is doing nothing. A plain client config file lists servers directly, each client owns its own copy, and there is no shared state. The difference in approach is where the aggregation lives. With a config file, aggregation is per client and per machine: five clients means five lists that drift. With MetaMCP, aggregation lives in a namespace on the server, and clients hold one endpoint entry each. That trade is real in both directions. You gain a single place to add a server, remove a tool, or rotate credentials, and you gain a place to attach auth and rate limiting, which the README documents as MCP rate limit under traffic management. You lose the ability to have a client-specific view without creating another namespace, and you take on a database. If your team is two people and three servers, the config file wins. The gateway starts winning when the number of clients or the number of servers makes drift expensive, or when you need an endpoint you can hand to someone else with a key attached.

## Licence and upgrade cost

MetaMCP is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is permissive and imposes no copyleft obligation on your own code. The practical cost sits elsewhere. Upgrades mean pulling a new image and running database migrations against the Postgres instance the compose file defines, so back up the database before you move a tag. The sed patch in the Dockerfile is version-pinned to a specific Next.js path; if you build your own image on a newer Next.js, verify that the substitution still matches, because a silent no-op there puts you back on the shorter proxy timeout. The pnpm overrides block in package.json pins minimum versions for a long list of transitive dependencies, including @modelcontextprotocol/sdk and several packages with security fixes, so dependency hygiene is being handled at the workspace level rather than by you. This is a description of the licence terms and the mechanics visible in the repository, not legal advice; if licence compliance matters to your organisation, have counsel review it.

## Conclusion

Adopt MetaMCP if you run several MCP servers and want one authenticated endpoint per group instead of duplicated client configs. Do not adopt it if you need a single STDIO server, or if you cannot run Postgres and the Docker image. Before committing, verify on your own machine that the namespace you build exposes exactly the tools you expect, that your client reaches the endpoint through the port and auth settings you configured, and that the ai-dev branch behaviour matches the release tag you intend to pin.

## FAQ

### What is MetaMCP?

It is an MCP proxy that aggregates MCP servers into a unified MCP server and applies middlewares, and it is itself an MCP server so it can be plugged into any MCP client. The README describes it as an aggregator, orchestrator, middleware and gateway in one Docker deployment.

### How to install MetaMCP?

The README recommends Docker Compose. The compose file pulls ghcr.io/metatool-ai/metamcp:latest, reads a .env file, and publishes port 12008, with Postgres connection details defaulting to host postgres on port 5432. There is also a Dev Containers setup for VSCode and Cursor and a local development path.

### How to use MetaMCP?

You register MCP servers, group them into namespaces, and assign public endpoints over SSE or Streamable HTTP with auth, switching which namespace an endpoint serves. Clients then connect to that endpoint instead of to each server individually.

### What is meta mcp?

The README describes MetaMCP as an MCP aggregator, orchestrator, middleware and gateway in one Docker deployment. It lets you dynamically aggregate MCP servers into a unified MCP server and apply middlewares, and it can be plugged into any MCP client.

## Sources

- [License: MIT](https://github.com/metatool-ai/metamcp/blob/ai-dev/LICENSE)
- [metatool-ai/metamcp on GitHub](https://github.com/metatool-ai/metamcp)
- [Project website](https://docs.metamcp.com)
- [README](https://github.com/metatool-ai/metamcp/blob/ai-dev/README.md)
- [Releases](https://github.com/metatool-ai/metamcp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/metatool-ai-metamcp