🚀 MetaMCP (Agregador MCP, Orquestador, Middleware, Gateway en un solo docker)

📢 Última actualización: Esta rama ai-dev será la rama de desarrollo en curso que contiene los cambios del agente de IA. Por favor, prueba antes de construir la imagen basada en esta rama. Ha habido muchos PRs gracias a la comunidad, pero fusionarlos y revisarlos también ha sido un esfuerzo creciente. Decidí incluir cambios de IA. Al menos hasta ahora la funcionalidad principal funciona. También hay un fork mantenido por la comunidad (¡muchas gracias!): https://github.com/Umbrella-IT-Group/metamcp

📢 Actualización: [Del autor: disculpas por el reciente retraso en el mantenimiento, pero al menos seguiré fusionando PRs, más contexto aquí]

MetaMCP es un proxy MCP que te permite agregar dinámicamente servidores MCP en un servidor MCP unificado y aplicar middlewares. MetaMCP en sí mismo es un servidor MCP, por lo que se puede conectar fácilmente a CUALQUIER cliente MCP.

Para más detalles, considera visitar nuestro sitio de documentación: https://docs.metamcp.com

English | 简体中文

📋 Tabla de contenidos

• 🎯 Casos de uso

• 📖 Conceptos

  • 🖥️ Servidor MCP

    • 🔐 Variables de entorno y secretos (servidores MCP STDIO)

  • 🏷️ Espacio de nombres de MetaMCP

  • 🌐 Endpoint de MetaMCP

  • ⚙️ Middleware

  • 🔍 Inspector

  • ✏️ Anulaciones y anotaciones de herramientas

• 🚀 Inicio rápido

  • 🐳 Ejecutar con Docker Compose (Recomendado)

  • 📦 Construir el entorno de desarrollo con Dev Containers (VSCode/Cursor)

  • 💻 Desarrollo local

• 🔌 Compatibilidad con el protocolo MCP

• 🔗 Conectar a MetaMCP

  • 📝 Ejemplo: Cursor mediante mcp.json

  • 🖥️ Conectar Claude Desktop y otros clientes solo STDIO

  • 🔧 Solución de problemas de autenticación con clave API

• ❄️ Problema de arranque en frío y Dockerfile personalizado

• 🧾 Niveles de registro

• 🔐 Autenticación

• 🚦 Gestión de tráfico

  • 🚧 Límite de tasa MCP

• 🔗 Soporte de proveedor OpenID Connect (OIDC)

  • 🛠️ Configuración

  • 🏢 Proveedores compatibles

  • 🔒 Características de seguridad

  • 📱 Uso

• ⚙️ Controles de registro

  • 🎛️ Controles disponibles

  • 🏢 Casos de uso empresariales

  • 🛠️ Configuración

• 🌐 Despliegue personalizado y configuración de SSE para Nginx

• 🏗️ Arquitectura

  • 📊 Diagrama de secuencia

• 🗺️ Hoja de ruta

• 🌐 i18n

• 🤝 Contribuciones

• 📄 Licencia

• 🙏 Créditos

Related MCP server: Master MCP Server

🎯 Casos de uso

• 🏷️ Agrupa servidores MCP en espacios de nombres, hostéalos como meta-MCP y asigna endpoints públicos (SSE o HTTP Streamable), con autenticación. Cambia de espacio de nombres para un endpoint con un solo clic.

• 🎯 Selecciona solo las herramientas que necesitas al remezclar servidores MCP. Aplica otros middlewares conectables en torno a observabilidad, seguridad, etc. (próximamente)

• 🔍 Úsalo como inspector MCP mejorado con configuraciones de servidor guardadas, e inspecciona tus endpoints de MetaMCP internamente para ver si funcionan o no.

• 🔍 Úsalo como Elasticsearch para la selección de herramientas MCP (próximamente)

En general, los desarrolladores pueden usar MetaMCP como infraestructura para alojar servidores MCP compuestos dinámicamente a través de un endpoint unificado, y construir agentes sobre él.

Video de demostración rápida: https://youtu.be/Cf6jVd2saAs

📖 Conceptos

🖥️ Servidor MCP

Una configuración de servidor MCP que le dice a MetaMCP cómo iniciar un servidor MCP.

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

🔐 Variables de entorno y secretos (servidores MCP STDIO)

Para servidores MCP STDIO, MetaMCP admite tres formas de manejar variables de entorno y secretos:

1. Valores sin procesar - Valores de cadena directos (no recomendado para secretos):

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

2. Referencias a variables de entorno - Usa la sintaxis ${ENV_VAR_NAME}:

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

3. Coincidencia automática - Si el nombre de la variable de entorno esperado en tu herramienta coincide con la variable de entorno del contenedor, puedes omitirlo por completo. MetaMCP pasará automáticamente las variables de entorno coincidentes.

🔒 Nota de seguridad: Las referencias a variables de entorno (${VAR_NAME}) se resuelven desde el entorno del contenedor de MetaMCP en tiempo de ejecución. Esto mantiene los valores reales de los secretos fuera de tu configuración y del repositorio de git.

⚙️ Nota de desarrollo: Para el desarrollo local con pnpm run dev:docker, asegúrate de que tus variables de entorno estén listadas en turbo.json bajo globalEnv para que se pasen a los procesos de desarrollo. Esto no es necesario para los despliegues de Docker en producción.

🏷️ Espacio de nombres de MetaMCP

• Agrupa uno o más servidores MCP en un espacio de nombres

• Habilita/deshabilita servidores MCP o a nivel de herramienta

• Aplica middlewares a las solicitudes y respuestas MCP

• Anula nombres/títulos/descripciones de herramientas por espacio de nombres y adjunta anotaciones MCP personalizadas (por ejemplo, { "annotations": { "readOnlyHint": false } })

🌐 Endpoint de MetaMCP

• Crea endpoints y asigna un espacio de nombres a los endpoints

• Múltiples servidores MCP en el espacio de nombres se agregarán y emitirán como un endpoint de MetaMCP

• Elige entre autenticación con clave API (en cabecera o parámetro de consulta) o OAuth estándar en la especificación MCP 2025-06-18

• Aloja a través de transportes SSE o HTTP Streamable en MCP y endpoints OpenAPI para clientes como Open WebUI

⚙️ Middleware

• Intercepta y transforma solicitudes y respuestas MCP a nivel de espacio de nombres

• Ejemplo integrado: "Filtrar herramientas inactivas" - optimiza el contexto de herramientas para LLMs

• Ideas futuras: registro de herramientas, trazas de errores, validación, escaneo

🔍 Inspector

Similar al inspector MCP oficial, pero con configuraciones de servidor guardadas - MetaMCP crea automáticamente configuraciones para que puedas depurar los endpoints de MetaMCP inmediatamente.

✏️ Anulaciones y anotaciones de herramientas

• Abre un espacio de nombres → pestaña Herramientas para ver cada herramienta proveniente de los servidores MCP conectados.

• Cada herramienta guardada se puede expandir y editar en línea: actualiza el nombre/título/descripción de visualización o proporciona un blob JSON con anotaciones específicas del espacio de nombres (por ejemplo, { "annotations": { "readOnlyHint": false } }).

• Las insignias en la tabla ("Anulado", "Anotaciones") muestran qué herramientas tienen actualmente metadatos personalizados. Pasa el cursor sobre ellas para leer una información sobre herramientas que describe lo que se anuló.

• Las anulaciones de anotaciones se fusionan con lo que devuelve el servidor MCP ascendente, por lo que puedes agregar sugerencias de interfaz de usuario personalizadas de manera segura sin perder los metadatos del proveedor.

🚀 Inicio rápido

🐳 Ejecutar con Docker Compose (Recomendado)

Clona el repositorio, prepara .env e inicia con docker compose:

git clone https://github.com/fanywebfx/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d
# pulls ghcr.io/fanywebfx/metamcp:ai-dev

Si modificas las variables de entorno APP_URL, asegúrate de acceder solo desde la APP_URL, porque MetaMCP aplica la política CORS en la URL, por lo que ninguna otra URL es accesible.

Los datos de SQLite se almacenan en un volumen de Compose (sqlite_data). Renombra ese volumen en docker-compose.yml si colisiona con otro proyecto.

📦 Construir el entorno de desarrollo con Dev Containers (VSCode/Cursor)

Puedes usar la extensión de VSCode/Cursor para construir el entorno de desarrollo en un contenedor.

Solo requiere que tengas un entorno con Docker o una alternativa similar (se requiere el comando docker/docker compose), y no es necesario instalar otros componentes dependientes en tu máquina host.

1. Primero, clona el código fuente de MetaMCP y abre el proyecto en Visual Studio Code.

git clone https://github.com/fanywebfx/metamcp.git
cd metamcp
code .

2. Cambia a Dev Containers. Abre la Paleta de Comandos de VSCode y ejecuta Dev Containers: Reopen in Container.

No necesitas crear .env primero. El contenedor copia example.env a .env.local al crearse, luego instala las dependencias y migra el archivo SQLite.

VSCode abrirá el proyecto de Dev Containers en una nueva ventana, donde construirá el runtime e instalará el toolchain según el Dockerfile antes de iniciar la conexión y finalmente instalar las dependencias de MetaMCP.

nota Este proceso requiere una conexión de red confiable, y accederá a Docker Hub, GitHub y algunos otros sitios. Deberás asegurar la conexión de red tú mismo, de lo contrario la construcción del contenedor puede fallar.

Espera algunos minutos, dependiendo de la conexión a internet o el rendimiento de la computadora, puede tomar desde unos minutos hasta decenas de minutos. Puedes hacer clic en la Barra de Progreso en la esquina inferior derecha para ver un registro en vivo donde podrás verificar si hay algún bloqueo inusual.

Después de terminar, puedes ejecutar pnpm dev para iniciar el servidor de desarrollo.

💻 Desarrollo local

SQLite se crea automáticamente en data/metamcp.db (relativo al directorio de trabajo del backend a menos que establezcas DATABASE_URL).

cp example.env .env.local
pnpm install
cd apps/backend && pnpm db:migrate:dev && cd ../..
pnpm dev

🔌 Compatibilidad con el protocolo MCP

• ✅ Tools, Resources y Prompts compatibles

• ✅ Servidores MCP con OAuth habilitado probados para la versión 03-26

Si tienes preguntas, no dudes en dejar GitHub issues o PRs.

🔗 Conectar a MetaMCP

📝 Ej., Cursor mediante mcp.json

Ejemplo de mcp.json

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

🖥️ Conexión de Claude Desktop y otros clientes solo stdio

Dado que los endpoints de MetaMCP son solo remotos (SSE, Streamable HTTP, OpenAPI), los clientes que solo admiten servidores stdio (como Claude Desktop) necesitan un proxy local para conectarse.

Nota: Aunque a veces se sugiere mcp-remote para este propósito, está diseñado para autenticación basada en OAuth y no funciona con la autenticación por clave API de MetaMCP. Según las pruebas, mcp-proxy es la solución recomendada.

Esta es una configuración que funciona para Claude Desktop usando mcp-proxy:

Usando 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>"
      }
    }
  }
}

Usando SSE

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

Notas importantes:

• Reemplaza <YOUR_ENDPOINT_NAME> por el nombre real de tu endpoint

• Reemplaza <YOUR_API_KEY_HERE> por tu clave API de MetaMCP (formato: sk_mt_...)

Para más detalles y enfoques alternativos, consulta el issue #76.

🔧 Solución de problemas de autenticación con clave API

• La autenticación con clave API mediante el parámetro ?api_key= no funciona para SSE. Solo funciona con Streamable HTTP y OpenAPI.

• La buena práctica es usar la clave API en el encabezado Authorization: Bearer <API_KEY>.

• Prueba a desactivar temporalmente la autenticación cuando tengas problemas de conexión para ver si se trata de un problema de autenticación.

❄️ Problema de arranque en frío y Dockerfile personalizado

• MetaMCP preasigna sesiones inactivas para cada servidor MCP y MetaMCP configurados. La cantidad predeterminada de sesiones inactivas para cada uno es 1, lo que puede contribuir a reducir el tiempo de arranque en frío.

• Si tu MCP requiere dependencias distintas de uvx o npx, debes personalizar el Dockerfile para instalar las dependencias por tu cuenta.

• Consulta invalidation.md para ver un diagrama de secuencia sobre cómo se invalida la sesión inactiva durante las actualizaciones.

🛠️ Solución: Personaliza el Dockerfile para añadir dependencias o preinstalar librerías y así reducir el tiempo de arranque en frío.

🧾 Levels de registro

El backend de MetaMCP escribe los registros en archivos y, opcionalmente, replica los niveles seleccionados en la consola. Controla la replicación en consola con la variable de entorno LOG_LEVEL.

• Archivos

  • app.log: recibe DEBUG, INFO y WARN

  • error.log: recibe ERROR

• Replicación en consola (LOG_LEVEL)

  • all: replica DEBUG, INFO, WARN, ERROR en la consola

  • info: replica solo INFO en la consola

  • errors-only: replica WARN y ERROR en la consola

  • none: sin réplica en consola

• Valores predeterminados y ejemplos

  • Predeterminado (cuando no está definido o es inválido): errors-only

  • Ejemplo de .env:

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

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

🔐 Autenticación

• 🛡️ Better Auth para el frontend y el backend (procedimientos TRPC)

• 🍪 Session cookies garantizan conexiones seguras del proxy MCP interno

• 🔑 Autenticación por clave API para el acceso externo mediante el encabezado Authorization: Bearer <api-key>

• 🪪 OAuth MCP: Los endpoints expuestos tienen opciones para usar OAuth estándar en MCP Spec 2025-06-18, de fácil conexión.

• 🏢 Multi-tenancy: Diseñado para que las organizaciones lo desplien en sus propias máquinas. Admite ámbitos de acceso privados y públicos. Los usuarios pueden crear MCPs, namespaces, endpoints y claves API para sí mismos o para todos. Las claves API públicas no pueden acceder a MetaMCPs privados.

• ⚙️ Controles de registro separados: Los administradores pueden controlar de forma independiente el registro desde la interfaz de usuario y el registro mediante SSO/OAuth a través de la página de ajustes, lo que permite escenarios de despliegue para empresas flexibles.

🚦 Gestión del tráfico

🚧 Límite de tasa MCP

La función Límite de tasa MCP permite establecer la cantidad máxima de peticiones que una herramienta MCP (un endpoint) aceptará en un periodo de tiempo determinado. Existen dos estrategias diferentes para establecer los límites, que puedes usar por separado o juntas:

• Endpoint rate-limiting (Rate Limiting): se aplica a la vez a todos los clientes que usan el endpoint, compartiendo un contador único.

• User rate-limiting (Client Rate Limiting): establece un contador para cada usuario individual.

Ambos tipos pueden coexistir y complementarse, y los contadores se guardan en memoria. En un clúster, cada máquina ve y cuenta solo el tráfico que pasa por ella.

Limitación por endpoint

La limitación por endpoint actúa sobre el número de transacciones simultáneas que un endpoint procesar. Este tipo de límite protege el servicio para todos los clientes. Cuando los usuarios que están conectados a una entity punto superan juntos el rate-limiting, MetaMCP empieza a rechazar conexiones con un código de estado 503 Service Unavailable.

Opciones de limitación por endpoint

• Max Rate: Define cuántas solicitudes aceptarás de todos los usuarios juntos en un instante determinado. Cuando se inicia la puerta de enlace, el bucket está lleno. A medida que llegan las solicitudes de los usuarios, los tokens restantes del bucket disminuyen. A su vez, el rate-limiting rellena el bucket lleno a la proporción deseada hasta su capacidad máxima.

• Max Rate Seconds: Periodo de tiempo en segundos en el que operan las rates Máximo. Por ejemplo, si configuras un max rate seconds de 60s y un rate-limiting de 5, permites 5 solicitudes cada 60 segundos.

Limitación por usuario

La limitación por usuario cuota aplica un contador a cada usuario individual y a cada endpoint. Cuando un único usuario conectado a un endpoint supera su client-max-rate, MetaMCP empieza a rechazar conexiones con un código de estado 429 Too Many Requests.

Opciones de limitación por usuario

• Client Max Rate: Número de tokens que añades al bucket de tokens para cada usuario individual (límite del usuario) en el intervalo que desees (Client Max Rate Seconds). Los tokens que quedan en el bucket son las solicitudes que un determinado usuario puede realizar.

• Client Max Rate Seconds: Periodo de tiempo en el que las tasas máximas operan en segundos. Por ejemplo, si configuras un intervalo de 60s y una tasa de 5, permites 5 solicitudes cada 60 segundos.

• Client Max Rate Strategy: Establece la estrategia que vas a usar para configurar los clients. Elige ip cuando las restricciones se apliquen a la dirección IP del cliente, o header cuando haya un encabezado que identifique al usuario de forma única. Ese encabezado debe definirse con la entrada de clave.(key).

• Client Max Rate Strategy Key: Es el nombre del encabezado que contiene la identificación del usuario (p. ej., Authorization para tokens o X-Original-Forwarded-For para IPs).

🔗 Compatibilidad con proveedores OpenID Connect (OIDC)

MetaMCP admite autenticación OpenID Connect para integrated with enterprise SSO. Permite a las plataformas usar sus proveedores de identidad existentes (Auth0, Keycloak, Azure AD, entre otros) para la autenticación.

🛠️ Configuración

Añade las siguientes variables de entorno a tu archivo .env:

# Required
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration

# Optional customization
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true

🏢 Proveedores compatibles

MetaMCP se ha probado con estos proveedores OIDC populares:

• Auth0: https://your-domain.auth0.com/.well-known/openid-configuration

• Keycloak: https://your-keycloak.com/realms/your-realm/.well-known/openid-configuration

• Azure AD: https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration

• Google: https://accounts.google.com/.well-known/openid-configuration

• Okta: https://your-domain.okta.com/.well-known/openid-configuration

🔒 Características de seguridad

• 🔐 PKCE (Proof Key for Code Exchange) habilitado de forma predeterminada

• 🛡️ Authorization Code Flow con creación automática de proyectos

• 🔄 Auto-discovery de los endpoints OIDC

• 🍪 **Gestión de sesión fluida con el sistema de autenticación **existente

📱 Uso

Una vez realizada la configuración, los usuarios verán un botón "Sign in with OIDC" en la página de login, junto con el formulario de correo o electrónico y contraseña. El flujo de autenticación crea automáticamente nuevos usuarios en el primer login.

Para ejemplos de configración más complete y resolución de problemas, consulta CONTRIBUTING.md.

⚙️ Controles de registro

MetaMCP ofrece controles separados para diferentes métodos de registro, lo que permite a los administradores ajustar las políticas de acceso de usuario para despliegues en empresas.

🎛️ Controles disponibles

• UI Registration: Controla si los usuarios pueden crear cuentas mediante el formulario de registro

• SSO Registration: Controla si los usuarios pueden crear cuentas mediante proveedores SSO/OAuth (OIDC, etc.)

🏢 Casos de uso empresariales

Esta separación permite escenarios empresariales habituales:

• Bloquear UI, permitir SSO: impide los registros manuales, permitiendo a los usuarios corporativos el uso de SSO

• Bloquear SSO, permitir UI: permite los registros manuales, restringiendo el acceso por SSO

• Bloquear ambos: descompetir completamente el nuevo registro de usuarios

• Permitir ambos: comportamiento predeterminado en entornos abiertos

🛠️ Configuración

Accede a la página Settings en la interfaz de administración de MetaMCP para configurar estos controles:

1. Ve a Settings → Authentication Settings

2. Alterna "Disable UI Registration" para registrar los formularios de registro

3. Alterna "Disable SSO Registration" para registrar los formularios de registro OAuth/OIDC

Ambos controles funcionan de forma independiente, por lo que tendrás plena flexibilidad para definir tu política de registro.

🌐 Despliegue personalizado y configuración SSE para Nginx

Si quieres instalarlo en un servicio en línea o en una VPS, necesitas una instancia con al menos 2 GB-4 GB de memoria. Cuanto mayor sea la instancia, mejor será su rendimiento.

Dado que MCP usa SSE para las conexiones largas, si estás usando un proxy inverso como nginx, consulta un ejemplo de configuración en nginx.conf.example

🏗️ Arquitectura

• Frontend: Next.js

• Backend: Express.js con tRPC, que aloja de MCP a través de TS SDK y proxy interno

• Auth: Better Auth

• Estructura: Monorepo independiente con Turborepo y publicación de Docker

📊 Diagram de secuencia

Nota: Prompts and resources follow patterns similar to tools.

sequenceDiagram
    participant MCPClient as MCP Client (e.g., Claude Desktop)
    participant MetaMCP as MetaMCP Server
    participant MCPServers as Installed MCP Servers

    MCPClient ->> MetaMCP: Request list tools

    loop For each listed MCP Server
        MetaMCP ->> MCPServers: Request list_tools
        MCPServers ->> MetaMCP: Return list of tools
    end

    MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
    MetaMCP ->> MCPClient: Return aggregated list of tools

    MCPClient ->> MetaMCP: Call tool
    MetaMCP ->> MCPServers: call_tool to target MCP Server
    MCPServers ->> MetaMCP: Return tool response
    MetaMCP ->> MCPClient: Return tool response

🗺️ Hoja de ruta

Posibles your next future steps:

• 🔌 Acceso a Admin API (headless)

• Primera de aplicación dinámica de reglas de búsqueda en los endpoints de MetaMCP

• 🛠️ Más middlewares

• 💬 Chat/Agent Playground

• 🧪 Pruebas y evaluación para la optimización de la selección de herramientas MCP

• ⚡ Generación dinámica de servidores MCP

🌐 i18n

Consulta README-i18n.md

Actualmente se admite en inglés (en) y chino (zh), pero se aceptan contribuciones.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta los detalles en CONTRIBUTING.md

📄 Licencia

MIT

Agradecemos que se mencione con backlnks de vuelta si tus proyectos utilizados el código.

🙏 Créditos

Parte de código se inspirado en:

• MCP Inspector

• MCP Proxy Server

No se ha utilizado el código directamente, pero estemos basados en ideas de:

• https://github.com/open-webui/openapi-servers

• https://github.com/open-webui/mcpo