MetaMCP: Unifying Model Context Protocol Servers with an All-in-One Gateway

Introduction

MetaMCP is an innovative project designed to streamline the management and deployment of Model Context Protocol (MCP) servers. It functions as a comprehensive proxy, enabling dynamic aggregation of various MCP servers into a single, unified endpoint. This powerful tool also allows for the application of custom middlewares, offering enhanced control over observability, security, and tool selection. Built with TypeScript and packaged for Docker, MetaMCP provides a robust infrastructure for hosting dynamically composed MCP servers and building advanced AI agents.

Installation

Getting started with MetaMCP is straightforward, especially using Docker Compose, which is the recommended method.

1. Clone the repository:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp

2. Prepare your environment file:

cp example.env .env

3. Start MetaMCP with Docker Compose:

docker compose up -d

Note: If you modify APP_URL environment variables, ensure you only access MetaMCP from the specified APP_URL as it enforces a CORS policy. Also, consider renaming the metamcp_postgres_data volume in docker-compose.yml if it conflicts with existing Docker volumes. For more detailed development setup, including Dev Containers, refer to the official documentation.

Examples

Connecting your MCP clients to MetaMCP is flexible, supporting various configurations.

Connecting via mcp.json (e.g., Cursor)

For clients that support mcp.json configuration, you can point them directly to your MetaMCP endpoint:

{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
    }
  }
}

Connecting STDIO-only Clients (e.g., Claude Desktop) with mcp-proxy

For clients that only support STDIO servers, like Claude Desktop, mcp-proxy is the recommended solution to bridge the connection to MetaMCP's remote endpoints (SSE, Streamable HTTP, OpenAPI).

Using Streamable HTTP:

{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

Using SSE:

{
  "mcpServers": {
    "ehn": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

Remember to replace <YOUR_ENDPOINT_NAME> and <YOUR_API_KEY_HERE> with your actual values. For API key authentication, using the Authorization: Bearer <API_KEY> header is generally the best practice. For more details, refer to issue #76.

Why Use MetaMCP?

MetaMCP offers a compelling set of features for developers and organizations working with Model Context Protocol servers:

• Unified Endpoint Management: Group multiple MCP servers into namespaces and expose them through a single, authenticated MetaMCP endpoint (SSE or Streamable HTTP, OpenAPI). This simplifies client connections and tool discovery.
• Customizable Tool Selection: Selectively pick tools from aggregated MCP servers and apply pluggable middlewares for enhanced control over observability, security, and more. You can also override tool metadata and attach custom annotations.
• Enhanced Inspection: Utilize MetaMCP as an advanced MCP inspector with saved server configurations, allowing for immediate debugging of your MetaMCP endpoints.
• Robust Authentication: Supports API key authentication, standard OAuth in MCP Spec 2025-06-18, and OpenID Connect (OIDC) for enterprise SSO integration (Auth0, Keycloak, Azure AD, Google, Okta). It also features multi-tenancy and separate registration controls for flexible deployment.
• Traffic Management: Implement MCP Rate Limiting at both endpoint and user levels to protect your services from overload and manage resource consumption effectively.
• Self-Hosted Flexibility: Designed for self-hosting, MetaMCP provides full control over your AI tool infrastructure, allowing for custom Dockerfile configurations to manage dependencies and cold start issues.

Links

• GitHub Repository: https://github.com/metatool-ai/metamcp
• Official Documentation: https://docs.metamcp.com
• Discord Community: https://discord.gg/mNsyat7mFX
• Demo Video: https://youtu.be/Cf6jVd2saAs