Metamcp

🚀 MetaMCP (MCP Aggregator, Orchestrator, Middleware, Gateway in one docker)

>

📢 Latest Update: This ai-dev branch will be the forward onging dev branch which contains ai agent changes. Please test before you build the image based on this branch. There has been many PRs thanks to the community but merging and reviewing them has been a growing effort too. I decided to include ai changes. At least so far the core functionality works. There is also a community maintained fork (ty a lot!): https://github.com/Umbrella-IT-Group/metamcp

📢 Update: [From the author: apologize for some recent maintainence delay, but will at least keep merging PRs, more background [here](recent-updates.md)]

MetaMCP is a MCP proxy that lets you dynamically aggregate MCP servers into a unified MCP server, and apply middlewares. MetaMCP itself is a MCP server so it can be easily plugged into ANY MCP clients.

---

For more details, consider visiting our documentation site: https://docs.metamcp.com

English | [简体中文](./README_cn.md)

📋 Table of Contents

• [🎯 Use Cases](#-use-cases)
• [📖 Concepts](#-concepts)
• [🖥️ MCP Server](#️-mcp-server)
• [🔐 Environment Variables \& Secrets (STDIO MCP Servers)](#-environment-variables--secrets-stdio-mcp-servers)
• [🏷️ MetaMCP Namespace](#️-metamcp-namespace)
• [🌐 MetaMCP Endpoint](#-metamcp-endpoint)
• [⚙️ Middleware](#️-middleware)
• [🔍 Inspector](#-inspector)
• [✏️ Tool Overrides \& Annotations](#️-tool-overrides--annotations)
• [🚀 Quick Start](#-quick-start)
• [🐳 Run with Docker Compose (Recommended)](#-run-with-docker-compose-recommended)
• [📦 Build development environment with Dev Containers (VSCode/Cursor)](#-build-development-environment-with-dev-containers-vscodecursor)
• [💻 Local Development](#-local-development)
• [🔌 MCP Protocol Compatibility](#-mcp-protocol-compatibility)
• [🔗 Connect to MetaMCP](#-connect-to-metamcp)
• [📝 E.g., Cursor via mcp.json](#-eg-cursor-via-mcpjson)
• [🖥️ Connecting Claude Desktop and Other STDIO-only Clients](#️-connecting-claude-desktop-and-other-stdio-only-clients)
• [🔧 API Key Auth Troubleshooting](#-api-key-auth-troubleshooting)
• [❄️ Cold Start Problem and Custom Dockerfile](#️-cold-start-problem-and-custom-dockerfile)
• [🧾 Log Levels](#-log-levels)
• [🔐 Authentication](#-authentication)
• [🚦 Traffic Management](#-traffic-management)
• [🚧 MCP Rate Limit](#-mcp-rate-limit)
• [🔗 OpenID Connect (OIDC) Provider Support](#-openid-connect-oidc-provider-support)
• [🛠️ Configuration](#️-configuration)
• [🏢 Supported Providers](#-supported-providers)
• [🔒 Security Features](#-security-features)
• [📱 Usage](#-usage)
• [⚙️ Registration Controls](#️-registration-controls)
• [🎛️ Available Controls](#️-available-controls)
• [🏢 Enterprise Use Cases](#-enterprise-use-cases)
• [🛠️ Configuration](#️-configuration-1)
• [🌐 Custom Deployment and SSE conf for Nginx](#-custom-deployment-and-sse-conf-for-nginx)
• [🏗️ Architecture](#️-architecture)
• [📊 Sequence Diagram](#-sequence-diagram)
• [🗺️ Roadmap](#️-roadmap)
• [🌐 i18n](#-i18n)
• [🤝 Contributing](#-contributing)
• [📄 License](#-license)
• [🙏 Credits](#-credits)

🎯 Use Cases

• 🏷️ Group MCP servers into namespaces, host them as meta-MCPs, and assign public endpoints (SSE or Streamable HTTP), with auth. One-click to switch a namespace for an endpoint.
• 🎯 Pick tools you only need when remixing MCP servers. Apply other pluggable middleware around observability, security, etc. (coming soon)
• 🔍 Use as enhanced MCP inspector with saved server configs, and inspect your MetaMCP endpoints in house to see if it works or not.
• 🔍 Use as Elasticsearch for MCP tool selection (coming soon)

Generally developers can use MetaMCP as infrastructure to host dynamically composed MCP servers through a unified endpoint, and build agents on top of it.

Quick demo video: https://youtu.be/Cf6jVd2saAs

📖 Concepts

🖥️ MCP Server

A MCP server configuration that tells MetaMCP how to start a MCP server.

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

🔐 Environment Variables & Secrets (STDIO MCP Servers)

For STDIO MCP servers, MetaMCP supports three ways to handle environment variables and secrets:

1. Raw Values - Direct string values (not recommended for secrets):

API_KEY=your-actual-api-key-here
DEBUG=true

2. Environment Variable References - Use ${ENV_VAR_NAME} syntax:

API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}

3. Auto-matching - If the expected environment variable name in your tool matches the container's environment variable, you can omit it entirely. MetaMCP will automatically pass through matching environment variables.

> 🔒 Security Note: Environment variable references (${VAR_NAME}) are resolved from the MetaMCP container's environment at runtime. This keeps actual secret values out of your configuration and git repository.

> ⚙️ Development Note: For local development with pnpm run dev:docker, ensure your environment variables are listed in turbo.json under globalEnv to be passed to the development processes. This is not required for production Docker deployments.

🏷️ MetaMCP Namespace

• Group one or more MCP servers into a namespace
• Enable/disable MCP servers or at tool level
• Apply middlewares to MCP requests and responses
• Override tool names/titles/descriptions per namespace and attach custom MCP annotations (e.g. { "annotations": { "readOnlyHint": false } })

🌐 MetaMCP Endpoint

• Create endpoints and assign namespace to endpoints
• Multiple MCP servers in the namespace will be aggregated and emitted as a MetaMCP endpoint
• Choose between API-Key Auth (in header or query param) or standard OAuth in MCP Spec 2025-06-18
• Host through SSE or Streamable HTTP transports in MCP and OpenAPI endpoints for clients like Open WebUI

⚙️ Middleware

• Intercepts and transforms MCP requests and responses at namespace level
• Built-in example: "Filter inactive tools" - optimizes tool context for LLMs
• Future ideas: tool logging, error traces, validation, scanning

🔍 Inspector

Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.

✏️ Tool Overrides & Annotations

• Open a namespace → Tools tab to see every tool coming from connected MCP servers.
• Each saved tool can be expanded and edited inline: update the display name/title/description or provide a JSON blob with namespace-specific annotations (for example { "annotations": { "readOnlyHint": false } }).
• Badges in the table ("Overridden", "Annotations") show which tools currently have custom metadata. Hover them to read a tooltip describing what was overridden.
• Annotation overrides are merged with whatever the upstream MCP server returns, so you can safely add custom UI hints without losing provider metadata.

🚀 Quick Start

🐳 Run with Docker Compose (Recommended)

Clone repo, prepare .env, and start with docker compose:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d

If you modify APPURL env vars, make sure you only access from the APPURL, because MetaMCP enforces CORS policy on the URL, so no other URL is accessible.

Note that the pg volume name may collide with your other pg dockers, which is global, consider rename it in docker-compose.yml:

volumes:
  metamcp_postgres_data:
    driver: local

📦 Build development environment with Dev Containers (VSCode/Cursor)

You can use the VSCode/Cursor extension to build the development environment in a container.

It only requires that you have an environment running Docker or a similar alternative (the docker/docker compose command is required), and no other dependent components need to be installed on your host machine.

1. First, clone the MetaMCP source code, open project in Visual Studio Code.

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

1. Switch to Dev Containers. Open the VSCode Command Palette, and execute Dev Containers: Reopen in Container.

VSCode will open the Dev Containers project in a new window, where it will build the runtime and install the toolchain according to the Dockerfile before starting the connection and finally installing the MetaMCP dependencies.

> note > This process requires a reliable network connection, and it will access Docker Hub, GitHub, and some other sites. You will need to ensure the network connection yourself, otherwise the container build may fail.

Wait some minutes, depending on the internet connection or computer performance, it may take from a few minutes to tens of minutes, you can click on the Progress Bar in the bottom right corner to view a live log where you will be able to check unusual stuck.

After finished, you can run pnpm dev to start the development server.

💻 Local Development

Still recommend running postgres through docker for easy setup:

pnpm install
pnpm dev

🔌 MCP Protocol Compatibility

• ✅ Tools, Resources, and Prompts supported
• ✅ OAuth-enabled MCP servers tested for 03-26 version

If you have questions, feel free to leave GitHub issues or PRs.

🔗 Connect to MetaMCP

📝 E.g., Cursor via mcp.json

Example mcp.json

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

🖥️ Connecting Claude Desktop and Other STDIO-only Clients

Since MetaMCP endpoints are remote only (SSE, Streamable HTTP, OpenAPI), clients that only support stdio servers (like Claude Desktop) need a local proxy to connect.

Note: While mcp-remote is sometimes suggested for this purpose, it's designed for OAuth-based authentication and doesn't work with MetaMCP's API key authentication. Based on testing, mcp-proxy is the recommended solution.

Here's a working configuration for Claude Desktop using mcp-proxy:

Using Streamable HTTP

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

Using SSE

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

Important notes:

• Replace `` with your actual endpoint name
• Replace ` with your MetaMCP API key (format: skmt...`)

For more details and alternative approaches, see issue #76.

🔧 API Key Auth Troubleshooting

• ?api_key= param api key auth doesn't work for SSE. It only works for Streamable HTTP and OpenAPI.
• Best practice is to use the API key in Authorization: Bearer header.
• Try disable auth temporarily when you face connection issues to see if it is an auth issue.

❄️ Cold Start Problem and Custom Dockerfile

• MetaMCP pre-allocate idle sessions for each configured MCP servers and MetaMCPs. The default idle session for each is 1 and that can help reduce cold start time.
• If your MCP requires dependencies other than uvx or npx, you need to customize the Dockerfile to install dependencies on your own.
• Check [invalidation.md](invalidation.md) for a seq diagram about how idle session invalidates during updates.

🛠️ Solution: Customize the Dockerfile to add dependencies or pre-install packages to reduce cold start time.

🧾 Log Levels

MetaMCP’s backend writes logs to files and optionally mirrors selected levels to the console. Control console mirroring with the LOG_LEVEL environment variable.

• Files
• app.log: receives DEBUG, INFO, and WARN
• error.log: receives ERROR

• Console mirroring (LOG_LEVEL)
• all: mirror DEBUG, INFO, WARN, ERROR to console
• info: mirror only INFO to console
• errors-only: mirror WARN and ERROR to console
• none: no console output

• Defaults and examples
• Default (when unset or invalid): errors-only
• .env example:

``bash LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none' ``

• docker-compose.dev.yml uses: LOG_LEVEL: ${LOG_LEVEL:-all}

🔐 Authentication

• 🛡️ Better Auth for frontend & backend (TRPC procedures)
• 🍪 Session cookies enforce secure internal MCP proxy connections
• 🔑 API key authentication for external access via Authorization: Bearer header
• 🪪 MCP OAuth: Exposed endpoints have options to use standard OAuth in MCP Spec 2025-06-18, easy to connect.
• 🏢 Multi-tenancy: Designed for organizations to deploy on their own machines. Supports both private and public access scopes. Users can create MCPs, namespaces, endpoints, and API keys for themselves or for everyone. Public API keys cannot access private MetaMCPs.
• ⚙️ Separate Registration Controls: Administrators can independently control UI registration and SSO/OAuth registration through the settings page, allowing for flexible enterprise deployment scenarios.

🚦 Traffic Management

🚧 MCP Rate Limit

The MCP Rate Limit feature allows you to set the maximum requests a MCP tool (a endpoint) will accept in a given time window. There are two different strategies to set limits that you can use separately or together:

• Endpoint rate-limiting (Rate Limiting): applies simultaneously to all clients using the endpoint, sharing a unique counter.
• User rate-limiting (Client Rate Limiting): sets a counter to each individual user.

Both types can coexist and they complement each other, and store the counters in-memory. On a cluster, each machine sees and counts only its passing traffic.

Endpoint rate-limiting

The endpoint rate limit acts on the number of simultaneous transactions an endpoint can process. This type of limit protects the service for all customers. When the users connected to an endpoint together exceed the rate-limiting, MetaMCP starts to reject connections with a status code 503 Service Unavailable.

Endpoint rate-limiting options

• Max Rate: Defines how many requests will you accept from all users together at any given instant. When the gateway starts, the bucket is full. As requests from users come, the remaining tokens in the bucket decrease. At the same time, the rate-limiting refills the bucket at the desired rate until its maximum capacity is reached.
• Max Rate Seconds: Time period in which the maximum rates operate in seconds. For instance, if you set an max rate seconds of 60s and a rate-limiting of 5, you are allowing 5 requests every sixty seconds.

User rate-limiting

The client or user rate limit applies one counter to each individual user and endpoint. When a single user connected to an endpoint exceeds their client-max-rate, MetaMCP starts rejecting connections with a status code 429 Too Many Requests

User rate-limiting options

• Client Max Rate: Number of tokens you add to the Token Bucket for each individual user (user quota) in the time interval you want (Client Max Rate Seconds). The remaining tokens in the bucket are the requests a specific user can do.
• Client Max Rate Seconds: Time period in which the maximum rates operate in seconds. For instance, if you set an every of 60s and a rate of 5, you are allowing 5 requests every sixty seconds.
• `Cli

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: metatool-ai
• Source: metatool-ai/metamcp
• License: MIT
• Homepage: https://docs.metamcp.com

Install and usage instructions live in the source repository linked above.