Skip to content
Back to search

metamcp

MCP Aggregator, Orchestrator, Middleware, Gateway in one docker

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/metatool-ai/metamcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/metatool-ai/metamcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/metatool-ai--metamcp/badge.svg)](/listings/metatool-ai--metamcp)

HTML

<a href="/listings/metatool-ai--metamcp"><img src="/api/listings/metatool-ai--metamcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**๐Ÿณ 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 .

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 505 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ๐Ÿš€ MetaMCP (MCP Aggregator, Orchestrator, Middleware, Gateway in one docker) <!-- omit in toc -->
  2. <div align="center">
  3. <div align="center">
  4. <a href="https://discord.gg/mNsyat7mFX" style="text-decoration: none;">
  5. <img src="https://img.shields.io/badge/Discord-MetaMCP-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" style="max-width: 100%;">
  6. </a>
  7. <a href="https://docs.metamcp.com" style="text-decoration: none;">
  8. <img src="https://img.shields.io/badge/Documentation-docs.metamcp.com-blue?style=flat-square&logo=book" alt="Documentation" style="max-width: 100%;">
  9. </a>
  10. <a href="https://opensource.org/licenses/MIT" style="text-decoration: none;">
  11. <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License" style="max-width: 100%;">
  12. </a>
  13. <a href="https://github.com/metatool-ai/metamcp/pkgs/container/metamcp" style="text-decoration: none;">
  14. <img src="https://img.shields.io/badge/GHCR-available-green.svg?style=flat-square&logo=github" alt="GHCR" style="max-width: 100%;">
  15. </a>
  16. <a href="https://deepwiki.com/metatool-ai/metamcp"><img src="https://img.shields.io/badge/DeepWiki-metatool--ai%2Fmetamcp-blue.svg?style=flat-square&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki: MetaMCP"></a>
  17. </div>
  18. </div>
  19. >
  20. **๐Ÿ“ข 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
  21. **๐Ÿ“ข Update:** *[From the author: apologize for some recent maintainence delay, but will at least keep merging PRs, more background [here](recent-updates.md)]*
  22. **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.
  23. ![MetaMCP Diagram](metamcp.svg)
  24. ---
  25. For more details, consider visiting our documentation site: https://docs.metamcp.com
  26. English | [็ฎ€ไฝ“ไธญๆ–‡](./README_cn.md)
  27. ## ๐Ÿ“‹ Table of Contents <!-- omit in toc -->
  28. - [๐ŸŽฏ Use Cases](#-use-cases)
  29. - [๐Ÿ“– Concepts](#-concepts)
  30. - [๐Ÿ–ฅ๏ธ **MCP Server**](#๏ธ-mcp-server)
  31. - [๐Ÿ” **Environment Variables \& Secrets (STDIO MCP Servers)**](#-environment-variables--secrets-stdio-mcp-servers)
  32. - [๐Ÿท๏ธ **MetaMCP Namespace**](#๏ธ-metamcp-namespace)
  33. - [๐ŸŒ **MetaMCP Endpoint**](#-metamcp-endpoint)
  34. - [โš™๏ธ **Middleware**](#๏ธ-middleware)
  35. - [๐Ÿ” **Inspector**](#-inspector)
  36. - [โœ๏ธ **Tool Overrides \& Annotations**](#๏ธ-tool-overrides--annotations)
  37. - [๐Ÿš€ Quick Start](#-quick-start)
  38. - [๐Ÿณ Run with Docker Compose (Recommended)](#-run-with-docker-compose-recommended)
  39. - [๐Ÿ“ฆ Build development environment with Dev Containers (VSCode/Cursor)](#-build-development-environment-with-dev-containers-vscodecursor)
  40. - [๐Ÿ’ป Local Development](#-local-development)
  41. - [๐Ÿ”Œ MCP Protocol Compatibility](#-mcp-protocol-compatibility)
  42. - [๐Ÿ”— Connect to MetaMCP](#-connect-to-metamcp)
  43. - [๐Ÿ“ E.g., Cursor via mcp.json](#-eg-cursor-via-mcpjson)
  44. - [๐Ÿ–ฅ๏ธ Connecting Claude Desktop and Other STDIO-only Clients](#๏ธ-connecting-claude-desktop-and-other-stdio-only-clients)
  45. - [๐Ÿ”ง API Key Auth Troubleshooting](#-api-key-auth-troubleshooting)
  46. - [โ„๏ธ Cold Start Problem and Custom Dockerfile](#๏ธ-cold-start-problem-and-custom-dockerfile)
  47. - [๐Ÿงพ Log Levels](#-log-levels)
  48. - [๐Ÿ” Authentication](#-authentication)
  49. - [๐Ÿšฆ Traffic Management](#-traffic-management)
  50. - [๐Ÿšง **MCP Rate Limit**](#-mcp-rate-limit)
  51. - [๐Ÿ”— OpenID Connect (OIDC) Provider Support](#-openid-connect-oidc-provider-support)
  52. - [๐Ÿ› ๏ธ **Configuration**](#๏ธ-configuration)
  53. - [๐Ÿข **Supported Providers**](#-supported-providers)
  54. - [๐Ÿ”’ **Security Features**](#-security-features)
  55. - [๐Ÿ“ฑ **Usage**](#-usage)
  56. - [โš™๏ธ Registration Controls](#๏ธ-registration-controls)
  57. - [๐ŸŽ›๏ธ **Available Controls**](#๏ธ-available-controls)
  58. - [๐Ÿข **Enterprise Use Cases**](#-enterprise-use-cases)
  59. - [๐Ÿ› ๏ธ **Configuration**](#๏ธ-configuration-1)
  60. - [๐ŸŒ Custom Deployment and SSE conf for Nginx](#-custom-deployment-and-sse-conf-for-nginx)
  61. - [๐Ÿ—๏ธ Architecture](#๏ธ-architecture)
  62. - [๐Ÿ“Š Sequence Diagram](#-sequence-diagram)
  63. - [๐Ÿ—บ๏ธ Roadmap](#๏ธ-roadmap)
  64. - [๐ŸŒ i18n](#-i18n)
  65. - [๐Ÿค Contributing](#-contributing)
  66. - [๐Ÿ“„ License](#-license)
  67. - [๐Ÿ™ Credits](#-credits)
  68. ## ๐ŸŽฏ Use Cases
  69. - ๐Ÿท๏ธ **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.
  70. - ๐ŸŽฏ **Pick tools you only need when remixing MCP servers.** Apply other **pluggable middleware** around observability, security, etc. (coming soon)
  71. - ๐Ÿ” **Use as enhanced MCP inspector** with saved server configs, and inspect your MetaMCP endpoints in house to see if it works or not.
  72. - ๐Ÿ” **Use as Elasticsearch for MCP tool selection** (coming soon)
  73. Generally developers can use MetaMCP as **infrastructure** to host dynamically composed MCP servers through a unified endpoint, and build agents on top of it.
  74. Quick demo video: https://youtu.be/Cf6jVd2saAs
  75. ![MetaMCP Screenshot](metamcp_screenshot.png)
  76. ## ๐Ÿ“– Concepts
  77. ### ๐Ÿ–ฅ๏ธ **MCP Server**
  78. A MCP server configuration that tells MetaMCP how to start a MCP server.
  79. ```json
  80. "HackerNews": {
  81. "type": "STDIO",
  82. "command": "uvx",
  83. "args": ["mcp-hn"]
  84. }
  85. ```
  86. #### ๐Ÿ” **Environment Variables & Secrets (STDIO MCP Servers)**
  87. For **STDIO MCP servers**, MetaMCP supports three ways to handle environment variables and secrets:
  88. **1. Raw Values** - Direct string values (not recommended for secrets):
  89. ```
  90. API_KEY=your-actual-api-key-here
  91. DEBUG=true
  92. ```
  93. **2. Environment Variable References** - Use `${ENV_VAR_NAME}` syntax:
  94. ```
  95. API_KEY=${OPENAI_API_KEY}
  96. DATABASE_URL=${DB_CONNECTION_STRING}
  97. ```
  98. **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.
  99. > **๐Ÿ”’ 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.
  100. > **โš™๏ธ 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.
  101. ### ๐Ÿท๏ธ **MetaMCP Namespace**
  102. - Group one or more MCP servers into a namespace
  103. - Enable/disable MCP servers or at tool level
  104. - Apply middlewares to MCP requests and responses
  105. - Override tool names/titles/descriptions per namespace and attach custom MCP annotations (e.g. `{ "annotations": { "readOnlyHint": false } }`)
  106. ### ๐ŸŒ **MetaMCP Endpoint**
  107. - Create endpoints and assign namespace to endpoints
  108. - Multiple MCP servers in the namespace will be aggregated and emitted as a MetaMCP endpoint
  109. - Choose between API-Key Auth (in header or query param) or standard OAuth in MCP Spec 2025-06-18
  110. - Host through **SSE** or **Streamable HTTP** transports in MCP and **OpenAPI** endpoints for clients like [Open WebUI](https://github.com/open-webui/open-webui)
  111. ### โš™๏ธ **Middleware**
  112. - Intercepts and transforms MCP requests and responses at namespace level
  113. - **Built-in example**: "Filter inactive tools" - optimizes tool context for LLMs
  114. - **Future ideas**: tool logging, error traces, validation, scanning
  115. ### ๐Ÿ” **Inspector**
  116. Similar to the official MCP inspector, but with **saved server configs** - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.
  117. ### โœ๏ธ **Tool Overrides & Annotations**
  118. - Open a namespace โ†’ **Tools** tab to see every tool coming from connected MCP servers.
  119. - 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 } }`).
  120. - Badges in the table ("Overridden", "Annotations") show which tools currently have custom metadata. Hover them to read a tooltip describing what was overridden.
  121. - Annotation overrides are merged with whatever the upstream MCP server returns, so you can safely add custom UI hints without losing provider metadata.
  122. ## ๐Ÿš€ Quick Start
  123. ### **๐Ÿณ Run with Docker Compose (Recommended)**
  124. Clone repo, prepare `.env`, and start with docker compose:
  125. ```bash
  126. git clone https://github.com/metatool-ai/metamcp.git
  127. cd metamcp
  128. cp example.env .env
  129. docker compose up -d
  130. ```
  131. 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.
  132. Note that the pg volume name may collide with your other pg dockers, which is global, consider rename it in `docker-compose.yml`:
  133. ```
  134. volumes:
  135. metamcp_postgres_data:
  136. driver: local
  137. ```
  138. ### **๐Ÿ“ฆ Build development environment with Dev Containers (VSCode/Cursor)**
  139. You can use the VSCode/Cursor extension to build the development environment in a container.
  140. 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.
  141. 1. First, clone the MetaMCP source code, open project in Visual Studio Code.
  142. ```bash
  143. git clone https://github.com/metatool-ai/metamcp.git
  144. cd metamcp
  145. code .
  146. ```
  147. 2. Switch to Dev Containers. Open the VSCode Command Palette, and execute `Dev Containers: Reopen in Container`.
  148. 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.
  149. <img width="895" height="153" alt="image" src="https://github.com/user-attachments/assets/d3e1420d-43c1-4ed6-9229-b91ea09c142a" />
  150. > **note**
  151. > 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.
  152. 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.
  153. <img width="732" height="173" alt="image" src="https://github.com/user-attachments/assets/6e5752f8-7353-4a8f-b489-c13daef6700e" />
  154. After finished, you can run `pnpm dev` to start the development server.
  155. ### **๐Ÿ’ป Local Development**
  156. Still recommend running postgres through docker for easy setup:
  157. ```bash
  158. pnpm install
  159. pnpm dev
  160. ```
  161. ## ๐Ÿ”Œ MCP Protocol Compatibility
  162. - โœ… **Tools, Resources, and Prompts** supported
  163. - โœ… **OAuth-enabled MCP servers** tested for 03-26 version
  164. If you have questions, feel free to leave **GitHub issues** or **PRs**.
  165. ## ๐Ÿ”— Connect to MetaMCP
  166. ### ๐Ÿ“ E.g., Cursor via mcp.json
  167. Example `mcp.json`
  168. ```json
  169. {
  170. "mcpServers": {
  171. "MetaMCP": {
  172. "url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
  173. }
  174. }
  175. }
  176. ```
  177. ### ๐Ÿ–ฅ๏ธ Connecting Claude Desktop and Other STDIO-only Clients
  178. 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.
  179. **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.
  180. Here's a working configuration for Claude Desktop using `mcp-proxy`:
  181. Using Streamable HTTP
  182. ```json
  183. {
  184. "mcpServers": {
  185. "MetaMCP": {
  186. "command": "uvx",
  187. "args": [
  188. "mcp-proxy",
  189. "--transport",
  190. "streamablehttp",
  191. "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
  192. ],
  193. "env": {
  194. "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
  195. }
  196. }
  197. }
  198. }
  199. ```
  200. Using SSE
  201. ```json
  202. {
  203. "mcpServers": {
  204. "ehn": {
  205. "command": "uvx",
  206. "args": [
  207. "mcp-proxy",
  208. "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
  209. ],
  210. "env": {
  211. "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
  212. }
  213. }
  214. }
  215. }
  216. ```
  217. **Important notes:**
  218. - Replace `<YOUR_ENDPOINT_NAME>` with your actual endpoint name
  219. - Replace `<YOUR_API_KEY_HERE>` with your MetaMCP API key (format: `sk_mt_...`)
  220. For more details and alternative approaches, see [issue #76](https://github.com/metatool-ai/metamcp/issues/76#issuecomment-3046707532).
  221. ### ๐Ÿ”ง API Key Auth Troubleshooting
  222. - `?api_key=` param api key auth doesn't work for SSE. It only works for Streamable HTTP and OpenAPI.
  223. - Best practice is to use the API key in `Authorization: Bearer <API_KEY>` header.
  224. - Try disable auth temporarily when you face connection issues to see if it is an auth issue.
  225. ## โ„๏ธ Cold Start Problem and Custom Dockerfile
  226. - 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.
  227. - If your MCP requires dependencies other than `uvx` or `npx`, you need to customize the Dockerfile to install dependencies on your own.
  228. - Check [invalidation.md](invalidation.md) for a seq diagram about how idle session invalidates during updates.
  229. ๐Ÿ› ๏ธ **Solution**: Customize the Dockerfile to add dependencies or pre-install packages to reduce cold start time.
  230. ## ๐Ÿงพ Log Levels
  231. MetaMCPโ€™s backend writes logs to files and optionally mirrors selected levels to the console. Control console mirroring with the `LOG_LEVEL` environment variable.
  232. - Files
  233. - `app.log`: receives `DEBUG`, `INFO`, and `WARN`
  234. - `error.log`: receives `ERROR`
  235. - Console mirroring (`LOG_LEVEL`)
  236. - `all`: mirror `DEBUG`, `INFO`, `WARN`, `ERROR` to console
  237. - `info`: mirror only `INFO` to console
  238. - `errors-only`: mirror `WARN` and `ERROR` to console
  239. - `none`: no console output
  240. - Defaults and examples
  241. - Default (when unset or invalid): `errors-only`
  242. - `.env` example:
  243. ```bash
  244. LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none'
  245. ```
  246. - `docker-compose.dev.yml` uses: `LOG_LEVEL: ${LOG_LEVEL:-all}`
  247. ## ๐Ÿ” Authentication
  248. - ๐Ÿ›ก๏ธ **Better Auth** for frontend & backend (TRPC procedures)
  249. - ๐Ÿช **Session cookies** enforce secure internal MCP proxy connections
  250. - ๐Ÿ”‘ **API key authentication** for external access via `Authorization: Bearer <api-key>` header
  251. - ๐Ÿชช **MCP OAuth**: Exposed endpoints have options to use standard OAuth in MCP Spec 2025-06-18, easy to connect.
  252. - ๐Ÿข **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.
  253. - โš™๏ธ **Separate Registration Controls**: Administrators can independently control UI registration and SSO/OAuth registration through the settings page, allowing for flexible enterprise deployment scenarios.
  254. ## ๐Ÿšฆ Traffic Management
  255. ### ๐Ÿšง MCP Rate Limit
  256. 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:
  257. * `Endpoint rate-limiting (Rate Limiting)`: applies simultaneously to all clients using the endpoint, sharing a unique counter.
  258. * `User rate-limiting (Client Rate Limiting)`: sets a counter to each individual user.
  259. 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.
  260. ### **Endpoint rate-limiting**
  261. 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.
  262. When the users connected to an endpoint together exceed the `rate-limiting`, MetaMCP starts to reject connections with a status code `503 Service Unavailable`.
  263. #### **Endpoint rate-limiting options**
  264. * `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.
  265. * `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.
  266. ### **User rate-limiting**
  267. 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`
  268. #### **User rate-limiting options**
  269. * `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.
  270. * `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.
  271. * `Client Max Rate Strategy`: Sets the strategy you will use to set client counters. Choose ip when the restrictions apply to the clientโ€™s IP address, or set it to header when there is a header that identifies a user uniquely. That header must be defined with the key entry.
  272. * `Client Max Rate Strategy Key`: It is the header name containing the user identification (e.g., Authorization on tokens, or X-Original-Forwarded-For for IPs).
  273. ## ๐Ÿ”— OpenID Connect (OIDC) Provider Support
  274. MetaMCP supports **OpenID Connect authentication** for enterprise SSO integration. This allows organizations to use their existing identity providers (Auth0, Keycloak, Azure AD, etc.) for authentication.
  275. ### ๐Ÿ› ๏ธ **Configuration**
  276. Add the following environment variables to your `.env` file:
  277. ```bash
  278. # Required
  279. OIDC_CLIENT_ID=your-oidc-client-id
  280. OIDC_CLIENT_SECRET=your-oidc-client-secret
  281. OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration
  282. # Optional customization
  283. OIDC_PROVIDER_ID=oidc
  284. OIDC_SCOPES=openid email profile
  285. OIDC_PKCE=true
  286. ```
  287. ### ๐Ÿข **Supported Providers**
  288. MetaMCP has been tested with popular OIDC providers:
  289. - **Auth0**: `https://your-domain.auth0.com/.well-known/openid-configuration`
  290. - **Keycloak**: `https://your-keycloak.com/realms/your-realm/.well-known/openid-configuration`
  291. - **Azure AD**: `https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration`
  292. - **Google**: `https://accounts.google.com/.well-known/openid-configuration`
  293. - **Okta**: `https://your-domain.okta.com/.well-known/openid-configuration`
  294. ### ๐Ÿ”’ **Security Features**
  295. - ๐Ÿ” **PKCE (Proof Key for Code Exchange)** enabled by default
  296. - ๐Ÿ›ก๏ธ **Authorization Code Flow** with automatic user creation
  297. - ๐Ÿ”„ **Auto-discovery** of OIDC endpoints
  298. - ๐Ÿช **Seamless session management** with existing auth system
  299. ### ๐Ÿ“ฑ **Usage**
  300. 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.
  301. For more detailed configuration examples and troubleshooting, see **[CONTRIBUTING.md](CONTRIBUTING.md#openid-connect-oidc-provider-setup)**.
  302. ## โš™๏ธ Registration Controls
  303. MetaMCP provides **separate controls** for different registration methods, allowing administrators to fine-tune user access policies for enterprise deployments.
  304. ### ๐ŸŽ›๏ธ **Available Controls**
  305. - **UI Registration**: Controls whether users can create accounts via the registration form
  306. - **SSO Registration**: Controls whether users can create accounts via SSO/OAuth providers (OIDC, etc.)
  307. ### ๐Ÿข **Enterprise Use Cases**
  308. This separation enables common enterprise scenarios:
  309. - **Block UI registration, allow SSO**: Prevent manual signups while allowing corporate SSO users
  310. - **Block SSO registration, allow UI**: Allow manual signups while restricting SSO access
  311. - **Block both**: Completely disable new user registration
  312. - **Allow both**: Default behavior for open deployments
  313. ### ๐Ÿ› ๏ธ **Configuration**
  314. Access the **Settings** page in the MetaMCP admin interface to configure these controls:
  315. 1. Navigate to **Settings** โ†’ **Authentication Settings**
  316. 2. Toggle **"Disable UI Registration"** to control form-based signups
  317. 3. Toggle **"Disable SSO Registration"** to control OAuth/OIDC signups
  318. Both controls work independently, giving you full flexibility over your registration policy.
  319. ## ๐ŸŒ Custom Deployment and SSE conf for Nginx
  320. 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.
  321. Since MCP leverages SSE for long connection, if you are using reverse proxy like nginx, please refer to an example setup [nginx.conf.example](nginx.conf.example)
  322. ## ๐Ÿ—๏ธ Architecture
  323. - **Frontend**: Next.js
  324. - **Backend**: Express.js with tRPC, hosting MCPs through TS SDK and internal proxy
  325. - **Auth**: Better Auth
  326. - **Structure**: Standalone monorepo with Turborepo and Docker publishing
  327. ### ๐Ÿ“Š Sequence Diagram
  328. *Note: Prompts and resources follow similar patterns to tools.*
  329. ```mermaid
  330. sequenceDiagram
  331. participant MCPClient as MCP Client (e.g., Claude Desktop)
  332. participant MetaMCP as MetaMCP Server
  333. participant MCPServers as Installed MCP Servers
  334. MCPClient ->> MetaMCP: Request list tools
  335. loop For each listed MCP Server
  336. MetaMCP ->> MCPServers: Request list_tools
  337. MCPServers ->> MetaMCP: Return list of tools
  338. end
  339. MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
  340. MetaMCP ->> MCPClient: Return aggregated list of tools
  341. MCPClient ->> MetaMCP: Call tool
  342. MetaMCP ->> MCPServers: call_tool to target MCP Server
  343. MCPServers ->> MetaMCP: Return tool response
  344. MetaMCP ->> MCPClient: Return tool response
  345. ```
  346. ## ๐Ÿ—บ๏ธ Roadmap
  347. **Potential next steps:**
  348. - [ ] ๐Ÿ”Œ Headless Admin API access
  349. - [ ] ๐Ÿ” Dynamically apply search rules on MetaMCP endpoints
  350. - [ ] ๐Ÿ› ๏ธ More middlewares
  351. - [ ] ๐Ÿ’ฌ Chat/Agent Playground
  352. - [ ] ๐Ÿงช Testing & Evaluation for MCP tool selection optimization
  353. - [ ] โšก Dynamically generate MCP servers
  354. ## ๐ŸŒ i18n
  355. See [README-i18n.md](README-i18n.md)
  356. Currently en and zh locale are supported, but welcome contributions.
  357. ## ๐Ÿค Contributing
  358. We welcome contributions! See details at **[CONTRIBUTING.md](CONTRIBUTING.md)**
  359. ## ๐Ÿ“„ License
  360. **MIT**
  361. Would appreciate if you mentioned with back links if your projects use the code.
  362. ## ๐Ÿ™ Credits
  363. Some code inspired by:
  364. - [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
  365. - [MCP Proxy Server](https://github.com/adamwattis/mcp-proxy-server)
  366. Not directly used the code by took ideas from
  367. - https://github.com/open-webui/openapi-servers
  368. - https://github.com/open-webui/mcpo

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.