MetaMCP is an MCP proxy that allows you to dynamically aggregate multiple MCP servers into a unified MCP server and apply middleware. MetaMCP itself is an MCP server, so it can be easily connected to any MCP client.
Core Concepts
- MCP Server: A configuration that tells MetaMCP how to start an MCP server. For STDIO MCP servers, three ways of handling environment variables and secrets are supported: raw values, environment variable references (${ENV_VAR_NAME} syntax), and automatic matching.
- MetaMCP Namespace: Groups one or more MCP servers, can enable/disable at the MCP server or tool level, applies middleware, overrides tool names/titles/descriptions, and attaches custom MCP annotations.
- MetaMCP Endpoint: Create an endpoint and assign namespaces to the endpoint; multiple MCP servers in the namespace will be aggregated into a single MetaMCP endpoint. Supports API key authentication or standard OAuth, over SSE or Streamable HTTP transport.
- Middleware: Intercepts and transforms MCP requests and responses at the namespace level. The built-in example "Filter Inactive Tools" can optimize the LLM's tool context.
- Inspector: Similar to the official MCP Inspector, but with saved server configurations, allowing immediate debugging of MetaMCP endpoints.
- Tool Overrides and Annotations: Edit tool names/titles/descriptions inline, or provide JSON annotations; annotation overrides are merged with the metadata returned by the upstream MCP server.
Key Capabilities
- Group MCP servers into namespaces, host them as a meta MCP, and assign public endpoints (SSE or Streamable HTTP) with authentication. Switch an endpoint's namespace with one click.
- When mixing MCP servers, select only the tools you need, and apply pluggable middleware (observability, security, etc., coming soon).
- Use as an enhanced MCP Inspector with saved server configurations, and check whether MetaMCP endpoints are working properly.
- Planned Elasticsearch for MCP tool selection (coming soon).
- Developers can use MetaMCP as infrastructure to host dynamically composed MCP servers through a unified endpoint and build agents on top of it.
Usage
Quick Start
Docker Compose is recommended: clone the repository, prepare the .env file, and start docker compose. You can also use Dev Containers (VSCode/Cursor) to build a development environment, or develop locally.
Connecting to MetaMCP
MetaMCP endpoints are remote-only (SSE, Streamable HTTP, OpenAPI). Clients that only support stdio (such as Claude Desktop) require a local proxy. mcp-proxy is recommended. The API key authentication format is sk_mt_..., and the best practice is to use it in the Authorization: Bearer <API_KEY> header.
Authentication
- The frontend and backend use Better Auth, and session cookies enforce secure internal MCP proxy connections.
- API key authentication is used for external access.
- MCP OAuth: Exposed endpoints can optionally use standard OAuth.
- Multi-tenancy: Supports private and public access scopes.
- Registration control: Administrators can independently control UI registration and SSO/OAuth registration.
Traffic Management
- Endpoint rate limiting: Applies to all clients, shares counters, and returns 503 when exceeded.
- User rate limiting: Sets counters for each user and endpoint, and returns 429 when exceeded.
OIDC Support
Supports OpenID Connect authentication and integrates with enterprise SSO (Auth0, Keycloak, Azure AD, etc.).
Use Cases
- Developers who need to aggregate multiple MCP servers into a unified endpoint for use by AI agents.
- Teams that want to dynamically compose MCP servers and apply middleware (such as observability and security).
- Organizations that need enterprise-grade features such as multi-tenancy, authentication, and rate limiting.
Limitations
- Some features (such as observability middleware and Elasticsearch tool selection) have not yet been launched.
- Clients that only support stdio require an additional proxy.
- Cold start issue: By default, 1 idle session is preallocated for each MCP server, but a custom Dockerfile may be needed to reduce cold start time.
- Environment variable references are resolved from the MetaMCP container environment.
- The documentation does not provide specificpricing or cost information.
