MetaMCP

Un middleware autoalojable para gestionar todos tus MCPs a través de una interfaz gráfica y un proxy local, compatible con múltiples clientes y espacios de trabajo.

GitHub
2.7k
Prueba este MCPPatrocinado

Documentación

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

📢 Última actualización: Esta rama ai-dev será la rama de desarrollo continua hacia adelante que contiene cambios de agentes 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 algún retraso reciente 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.

MetaMCP Diagram

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

English | 简体中文

📋 Tabla de Contenidos

🎯 Casos de Uso

  • 🏷️ Agrupa servidores MCP en espacios de nombres, hostéalos como meta-MCPs 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 MetaMCP internamente para ver si funcionan o no.
  • 🔍 Úsalo como Elasticsearch para la selección de herramientas MCP (próximamente)

Generalmente, 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

MetaMCP Screenshot

📖 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 Crudos - 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 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 MetaMCP en tiempo de ejecución. Esto mantiene los valores secretos reales fuera de tu configuración y del repositorio 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 despliegues de producción en Docker.

🏷️ Espacio de Nombres 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 MetaMCP

  • Crea endpoints y asigna espacios de nombres a los endpoints
  • Múltiples servidores MCP en el espacio de nombres se agregarán y emitirán como un endpoint MetaMCP
  • Elige entre Autenticación con Clave API (en encabezado 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 MetaMCP de inmediato.

✏️ 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 qué se anuló.
  • Las anulaciones de anotaciones se fusionan con lo que devuelve el servidor MCP ascendente, por lo que puedes agregar sugerencias de interfaz personalizadas de manera segura sin perder los metadatos del proveedor.

🚀 Inicio Rápido

🐳 Ejecutar con Docker Compose (Recomendado)

Clona el repositorio, prepara .env y comienza con docker compose:

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

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

Ten en cuenta que el nombre del volumen pg puede colisionar con otros dockers pg, que es global; considera renombrarlo en docker-compose.yml:

volumes:
  metamcp_postgres_data:
    driver: local

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

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

Solo requiere que tengas un entorno con Docker o una alternativa similar (el comando docker/docker compose es necesario), 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/metatool-ai/metamcp.git
cd metamcp
code .
  1. Cambia a Dev Containers. Abre la Paleta de Comandos de VSCode y ejecuta Dev Containers: Reopen in Container.

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

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

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

💻 Desarrollo Local

Aún se recomienda ejecutar postgres a través de docker para una configuración fácil:

pnpm install
pnpm dev

🔌 Compatibilidad con el Protocolo MCP

  • ✅ Herramientas, Recursos y Prompts soportados
  • ✅ Servidores MCP habilitados para OAuth probados para la versión 03-26

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

🔗 Conectar a MetaMCP

📝 Ejemplo: Cursor mediante mcp.json

Ejemplo mcp.json

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

🖥️ Conectar Claude Desktop y Otros Clientes Solo-STDIO

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

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

Aquí hay una configuración funcional para Claude Desktop usando mcp-proxy:

Usando HTTP Streamable

{
  "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> con el nombre real de tu endpoint
  • Reemplaza <YOUR_API_KEY_HERE> con tu clave API de MetaMCP (formato: sk_mt_...)

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

🔧 Solución de Problemas de Autenticación con Clave API

  • El parámetro ?api_key= de autenticación con clave API no funciona para SSE. Solo funciona para HTTP Streamable y OpenAPI.
  • La mejor práctica es usar la clave API en el encabezado Authorization: Bearer <API_KEY>.
  • Intenta deshabilitar la autenticación temporalmente cuando enfrentes problemas de conexión para ver si es 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 sesión inactiva predeterminada para cada uno es 1 y eso puede ayudar a reducir el tiempo de arranque en frío.
  • Si tu MCP requiere dependencias distintas de uvx o npx, necesitas personalizar el Dockerfile para instalar dependencias por tu cuenta.
  • Consulta invalidation.md para un diagrama de secuencia sobre cómo se invalidan las sesiones inactivas durante las actualizaciones.

🛠️ Solución: Personaliza el Dockerfile para agregar dependencias o preinstalar paquetes para reducir el tiempo de arranque en frío.

🧾 Niveles de Registro

El backend de MetaMCP escribe registros en archivos y opcionalmente refleja los niveles seleccionados en la consola. Controla el reflejo en la consola con la variable de entorno LOG_LEVEL.

  • Archivos

    • app.log: recibe DEBUG, INFO y WARN
    • error.log: recibe ERROR

  • Reflejo en consola (LOG_LEVEL)

    • all: refleja DEBUG, INFO, WARN y ERROR en la consola
    • info: refleja solo INFO en la consola
    • errors-only: refleja WARN y ERROR en la consola
    • none: sin salida en consola

  • Valores predeterminados y ejemplos

    • Predeterminado (cuando no se establece 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 frontend y backend (procedimientos TRPC)
  • 🍪 Cookies de sesión aseguran conexiones proxy MCP internas
  • 🔑 Autenticación por clave API para acceso externo mediante el encabezado Authorization: Bearer <api-key>
  • 🪪 OAuth MCP: Los endpoints expuestos tienen opciones para usar OAuth estándar en la especificación MCP 2025-06-18, fácil de conectar.
  • 🏢 Multi-tenant: Diseñado para que organizaciones lo desplieguen en sus propias máquinas. Soporta á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 de UI y el registro SSO/OAuth a través de la página de configuración, lo que permite escenarios de despliegue empresarial flexibles.

🚦 Gestión de tráfico

🚧 Límite de tasa MCP

La función de límite de tasa MCP permite establecer el máximo de solicitudes que una herramienta MCP (un endpoint) aceptará en un período de tiempo determinado. Hay dos estrategias diferentes para establecer límites que puedes usar por separado o juntas:

  • Endpoint rate-limiting (Rate Limiting): se aplica simultáneamente 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 se complementan entre sí, y almacenan los contadores en memoria. En un clúster, cada máquina ve y cuenta solo su tráfico que pasa.

Límite de tasa de endpoint

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

Opciones de límite de tasa de endpoint

  • Max Rate: Define cuántas solicitudes aceptarás de todos los usuarios juntos en cualquier instante dado. Cuando la puerta de enlace se inicia, el depósito está lleno. A medida que llegan solicitudes de los usuarios, los tokens restantes en el depósito disminuyen. Al mismo tiempo, el limitador de tasa rellena el depósito a la tasa deseada hasta alcanzar su capacidad máxima.
  • Max Rate Seconds: Período de tiempo en el que operan las tasas máximas, en segundos. Por ejemplo, si estableces un máximo de segundos de tasa de 60s y un límite de tasa de 5, estás permitiendo 5 solicitudes cada sesenta segundos.

Límite de tasa de usuario

El límite de tasa de cliente o usuario aplica un contador a cada usuario individual y endpoint. Cuando un solo usuario conectado a un endpoint supera su client-max-rate, MetaMCP comienza a rechazar conexiones con un código de estado 429 Too Many Requests

Opciones de límite de tasa de usuario

  • Client Max Rate: Número de tokens que agregas al depósito de tokens para cada usuario individual (cuota de usuario) en el intervalo de tiempo que desees (segundos de tasa máxima de cliente). Los tokens restantes en el depósito son las solicitudes que un usuario específico puede hacer.
  • Client Max Rate Seconds: Período de tiempo en el que operan las tasas máximas, en segundos. Por ejemplo, si estableces un cada de 60s y una tasa de 5, estás permitiendo 5 solicitudes cada sesenta segundos.
  • Client Max Rate Strategy: Establece la estrategia que usarás para establecer contadores de cliente. Elige ip cuando las restricciones se apliquen a la dirección IP del cliente, o configúralo como header cuando haya un encabezado que identifique a un usuario de manera única. Ese encabezado debe definirse con la entrada de clave.
  • Client Max Rate Strategy Key: Es el nombre del encabezado que contiene la identificación del usuario (por ejemplo, Authorization en tokens, o X-Original-Forwarded-For para IPs).

🔗 Soporte de proveedor OpenID Connect (OIDC)

MetaMCP soporta autenticación OpenID Connect para integración SSO empresarial. Esto permite a las organizaciones usar sus proveedores de identidad existentes (Auth0, Keycloak, Azure AD, etc.) para la autenticación.

🛠️ Configuración

Agrega 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 ha sido probado con 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 (Prueba de clave para intercambio de código) habilitado por defecto
  • 🛡️ Flujo de código de autorización con creación automática de usuarios
  • 🔄 Auto-descubrimiento de endpoints OIDC
  • 🍪 Gestión de sesiones sin interrupciones con el sistema de autenticación existente

📱 Uso

Una vez configurado, los usuarios verán un botón "Iniciar sesión con OIDC" en la página de inicio de sesión junto al formulario de correo electrónico/contraseña. El flujo de autenticación crea automáticamente nuevos usuarios en el primer inicio de sesión.

Para ejemplos de configuración más detallados y solución de problemas, consulta CONTRIBUTING.md.

⚙️ Controles de registro

MetaMCP proporciona controles separados para diferentes métodos de registro, lo que permite a los administradores ajustar las políticas de acceso de usuarios para despliegues empresariales.

🎛️ Controles disponibles

  • Registro de UI: Controla si los usuarios pueden crear cuentas a través del formulario de registro
  • Registro SSO: Controla si los usuarios pueden crear cuentas a través de proveedores SSO/OAuth (OIDC, etc.)

🏢 Casos de uso empresarial

Esta separación permite escenarios empresariales comunes:

  • Bloquear registro de UI, permitir SSO: Evitar registros manuales mientras se permite a usuarios SSO corporativos
  • Bloquear registro SSO, permitir UI: Permitir registros manuales mientras se restringe el acceso SSO
  • Bloquear ambos: Deshabilitar completamente el registro de nuevos usuarios
  • Permitir ambos: Comportamiento predeterminado para despliegues abiertos

🛠️ Configuración

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

  1. Navega a Configuración → Configuración de autenticación
  2. Alterna "Deshabilitar registro de UI" para controlar los registros basados en formularios
  3. Alterna "Deshabilitar registro SSO" para controlar los registros OAuth/OIDC

Ambos controles funcionan de forma independiente, brindándote total flexibilidad sobre tu política de registro.

🌐 Despliegue personalizado y configuración SSE para Nginx

Si deseas desplegarlo en un servicio en línea o un VPS, se requiere una instancia de al menos 2GB-4GB de memoria. Y cuanto mayor sea el tamaño, mejor será el rendimiento.

Dado que MCP utiliza SSE para conexiones largas, si usas un proxy inverso como nginx, consulta un ejemplo de configuración nginx.conf.example

🏗️ Arquitectura

  • Frontend: Next.js
  • Backend: Express.js con tRPC, alojando MCPs a través del SDK de TS y proxy interno
  • Autenticación: Better Auth
  • Estructura: Monorepo independiente con Turborepo y publicación Docker

📊 Diagrama de secuencia

Nota: Los prompts y recursos siguen patrones similares a las herramientas.

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 próximos pasos:

  • 🔌 Acceso API de administración sin interfaz
  • 🔍 Aplicar dinámicamente reglas de búsqueda en endpoints MetaMCP
  • 🛠️ Más middlewares
  • 💬 Chat/Playground de agentes
  • 🧪 Pruebas y evaluación para la optimización de selección de herramientas MCP
  • ⚡ Generar dinámicamente servidores MCP

🌐 i18n

Consulta README-i18n.md

Actualmente se admiten las configuraciones regionales en e inglés y chino, pero se agradecen contribuciones.

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! Consulta los detalles en CONTRIBUTING.md

📄 Licencia

MIT

Agradeceríamos que mencionaras con enlaces de retroceso si tus proyectos usan el código.

🙏 Créditos

Algo de código inspirado en:

No se usó directamente el código, pero se tomaron ideas de