metamcp MCP工具

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

</div>

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

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 | 中文

**🐳 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 APP_URL env vars, make sure you only access from the APP_URL, 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 .

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. <img width="895" height="153" alt="image" src="https://github.com/user-attachments/assets/d3e1420d-43c1-4ed6-9229-b91ea09c142a" />

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. <img width="732" height="173" alt="image" src="https://github.com/user-attachments/assets/6e5752f8-7353-4a8f-b489-c13daef6700e" />

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

❄️ 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 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.

🌐 Custom Deployment and SSE conf for Nginx

If you want to deploy it to a online service or a VPS, a instance of at least 2GB-4GB of memory is required. And the larger size, the better performance.

Since MCP leverages SSE for long connection, if you are using reverse proxy like nginx, please refer to an example setup nginx.conf.example

🎯 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

🚀 Quick Start

📱 **Usage**

Once configured, users will see a "Sign in with OIDC" button on the login page alongside the email/password form. The authentication flow automatically creates new users on first login.

For more detailed configuration examples and troubleshooting, see CONTRIBUTING.md.

🏢 **Enterprise Use Cases**

This separation enables common enterprise scenarios:

• Block UI registration, allow SSO: Prevent manual signups while allowing corporate SSO users
• Block SSO registration, allow UI: Allow manual signups while restricting SSO access
• Block both: Completely disable new user registration
• Allow both: Default behavior for open deployments

🛠️ **Configuration**

Add the following environment variables to your .env file:

```bash

Optional customization

OIDC_PROVIDER_ID=oidc OIDC_SCOPES=openid email profile OIDC_PKCE=true ```

🛠️ **Configuration**

Access the Settings page in the MetaMCP admin interface to configure these controls:

1. Navigate to Settings → Authentication Settings
2. Toggle "Disable UI Registration" to control form-based signups
3. Toggle "Disable SSO Registration" to control OAuth/OIDC signups

Both controls work independently, giving you full flexibility over your registration policy.

🌐 **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

**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.

🔧 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 <API_KEY> header.
• Try disable auth temporarily when you face connection issues to see if it is an auth issue.