mcp-multiplexer

Meta-servidor que se sitúa frente a todos tus servidores MCP con 7 meta-herramientas de carga diferida: ahorra ~95% de los tokens del esquema de herramientas.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-multiplexer

Un servidor MCP que actúa como fachada para muchos. Apunta tu cliente de IA al multiplexor y este presenta 7 meta-herramientas en lugar de los esquemas completos de herramientas de cada servidor upstream — reduciendo drásticamente los tokens gastados en cargar definiciones de herramientas en el contexto del modelo al inicio de la sesión.

Qué hace

Cada servidor MCP que configures empuja todos sus esquemas de herramientas al contexto del modelo desde el principio. Con una docena de servidores, eso son decenas de miles de tokens que el modelo casi nunca usa. mcp-multiplexer es un servidor MCP (basado en comandos stdio y upstreams HTTP remotos) que expone solo:

Meta-herramienta	Qué devuelve
`list_servers`	Resumen: nombre, estado, número de herramientas, instrucciones
`list_tools(server)`	Nombres de herramientas, descripciones de una línea, anotaciones — sin esquemas
`search_tools(query, server?, limit=5)`	Herramientas coincidentes con esquemas de entrada completos
`describe_tool(server, tool)`	Esquema de entrada completo de una herramienta exacta
`call_tool(server, tool, arguments)`	Llamada proxy; resultados devueltos textualmente
`refresh_tools(server?)`	Reconectar y reconstruir el índice de herramientas
`authorize_server(server, pasted_url?)`	Iniciar/completar inicio de sesión OAuth para un servidor

El modelo descubre herramientas de forma perezosa — primero lista y busca, obtiene un esquema completo solo cuando está a punto de llamar. El índice de herramientas se almacena en caché en ~/.cache/mcp-multiplexer/index.json para un inicio instantáneo, y los servidores upstream se conectan de forma perezosa.

Instalación

Binario precompilado (Linux x86_64/ARM64, macOS Intel/ARM, Windows x86_64 — sin necesidad de Rust): descarga el archivo para tu plataforma desde Releases y coloca mcp-multiplexer en tu PATH.

# example: Linux x86_64
curl -L https://github.com/johgirard/mcp-multiplexer/releases/latest/download/mcp-multiplexer-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo install mcp-multiplexer /usr/local/bin/

Desde el código fuente:

cargo install mcp-multiplexer

Cualquiera de las dos opciones también instala mcp-mock, un pequeño servidor de eco utilizado por el conjunto de pruebas — inofensivo, ignóralo.

Configuración

Formato estándar mcpServers (compatible con Claude Code / Claude Desktop), además de extras por servidor:

expose: booleano — las herramientas de este servidor también aparecen directamente como server__tool, omitiendo las meta-herramientas. Ver Modo híbrido: expose.
allow: lista de nombres exactos o globs prefix* — solo estas herramientas son visibles.
deny: lista, siempre tiene prioridad sobre allow.
connect_timeout: segundos — tiempo de espera de conexión/inicio (predeterminado 10). Auméntalo para servidores locales lentos al iniciar, p. ej. uvx --from git+… que compila en cada inicio en frío.

Las cadenas en command, args, env, url y headers admiten expansión de entorno ${VAR} (igual que Claude Code). Una variable no definida o un ${ sin cerrar falla al iniciar con un error claro — así que mantén los secretos fuera de la configuración:

{
  "$schema": "https://raw.githubusercontent.com/johgirard/mcp-multiplexer/main/schema.json",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/docs"],
      "allow": ["read_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "web": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" },
      "deny": ["admin_*"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp",
      "oauth": true
    },
    "fast": {
      "command": "mcp-fast-server",
      "expose": true
    }
  }
}

Ejecuta con mcp-multiplexer --config /path/to/.mcp.json (por defecto ./.mcp.json).

Modo híbrido: `expose`

La multiplexación intercambia un salto de descubrimiento (list_tools → describe_tool → call_tool) por un contexto de inicio casi vacío. Para servidores que llamas cada sesión, muchas veces, ese salto es pura sobrecarga — ya conoces la herramienta, y su esquema cuesta un puñado de tokens. Establece "expose": true y las herramientas de ese servidor se montan directamente como herramientas server__tool de primera clase, esquema incluido, junto a las meta-herramientas:

"serena": { "command": "uvx", "args": ["serena", "start-mcp-server"], "expose": true }

El modelo entonces llama a serena__find_symbol como cualquier herramienta conectada directamente — sin búsqueda, sin descripción, sin salto de proxy. El servidor sigue siendo accesible a través de las meta-herramientas también, y allow/deny siguen aplicándose. Regla general: multiplexa la flota, expón los favoritos.

OAuth

Los servidores remotos que hablan OAuth 2.1 (la especificación de autorización MCP) funcionan con "oauth": true en un servidor url — sin otra configuración en el caso común:

El primer uso falla con una URL de autorización. Ábrela, aprueba; un listener temporal 127.0.0.1 completa el intercambio. Reintenta la llamada y funciona. El modelo también puede manejarlo por sí mismo a través de la meta-herramienta authorize_server.
Los tokens viven en ~/.cache/mcp-multiplexer/tokens.json (modo 0600), se actualizan automáticamente y sobreviven a los reinicios — autoriza una vez por servidor.

Los ámbitos se descubren automáticamente; se utiliza el registro dinámico de clientes cuando el proveedor lo admite — y se auto-repara cuando un proveedor olvida el registro. Los proveedores que delegan la autenticación a un dominio diferente del endpoint MCP (emisores entre dominios) funcionan sin configuración adicional. Guía completa — flujo de pegado sin cabeza, ajuste de oauth_client_id / oauth_scopes / oauth_redirect_port, notas del proveedor (la trampa del interruptor de grupo de GitLab), solución de problemas: docs/oauth.md.

Claude Code

Reemplaza todas tus entradas mcpServers con una que apunte al multiplexor:

{
  "mcpServers": {
    "mux": {
      "command": "mcp-multiplexer",
      "args": ["--config", "/home/me/.mcp.json"]
    }
  }
}

Plugin (hace esto por ti): este repositorio es un plugin de Claude Code cuya habilidad setup instala el binario, migra tus servidores existentes a una configuración de multiplexor (los secretos se convierten en referencias ${VAR}, los servidores OAuth se marcan), reconfigura tu cliente y verifica:

/plugin marketplace add JohGirard/mcp-multiplexer
/plugin install mcp-multiplexer@mcp-multiplexer

Luego pide a Claude que "configure mcp-multiplexer" (o ejecuta /mcp-multiplexer:setup).

Cuando cambian las herramientas upstream

El índice se construye en la primera conexión y se almacena en caché en disco. Si un servidor upstream agrega o elimina herramientas, llama a refresh_tools (opcionalmente con un nombre de servidor) para re-indexar — sin necesidad de reiniciar. call_tool también se auto-repara: una llamada fallida activa una reconexión, re-indexación y reintento antes de mostrar el error.

Docker

docker build -t mcp-multiplexer .
docker run -i -v $HOME/.mcp.json:/config/.mcp.json:ro mcp-multiplexer

El modo Docker es solo para upstreams HTTP/remotos — los upstreams stdio necesitan sus runtimes (node, uv, …) dentro de la imagen.

Registro de actividad

--log-file <path> agrega registros a un archivo; de lo contrario, los registros van a stderr (stdout es solo protocolo — no lo canalices ni lo redirijas).
La variable de entorno RUST_LOG controla el nivel (p. ej. RUST_LOG=debug); --verbose es una abreviatura para el registro de depuración.

Estadísticas

mcp-multiplexer --stats imprime lo que el mux te está ahorrando (sin inicio de servidor; lee ~/.cache/mcp-multiplexer/):

Startup context per session:
  without mux: ~16333 tokens (46 tools)
  with mux:    ~553 tokens (meta-tools)
  saved:       ~15780 tokens (96%)

(ejemplo: un servidor GitLab) más bytes de esquema bajo demanda servidos, recuentos de llamadas proxy y uso por meta-herramienta. Los tokens se estiman como bytes/4 — una heurística, no un tokenizador real. Con el plugin de Claude Code instalado, /mcp-multiplexer:gain muestra el mismo informe en el chat.

No objetivos

Recursos y prompts de MCP (solo herramientas).
Muestreo upstream, elicitación y raíces.
Sin truncamiento de resultados de herramientas — devueltos textualmente.
OAuth solo para servidores url (los servidores stdio usan env para secretos).
Sin reenvío de notificaciones tools/list_changed — usa refresh_tools.

Desarrollo

Las contribuciones son bienvenidas — ver CONTRIBUTING.md para la configuración y la lista de verificación de CI, y SECURITY.md para reportar vulnerabilidades.

src/bin/mcp-mock.rs compila un binario de desarrollo mcp-mock (herramientas echo/add/fail) utilizado por las pruebas de integración.

cargo test

Depura interactivamente con el MCP Inspector — ten en cuenta el --, que evita que el propio flag --config del inspector consuma el nuestro:

npx @modelcontextprotocol/inspector --web -- \
  mcp-multiplexer --config /path/to/.mcp.json

Lanzamientos

CHANGELOG.md documenta cada lanzamiento. Para crear uno:

Agrega una sección ## [X.Y.Z] a CHANGELOG.md y aumenta version en Cargo.toml.
Haz commit como chore: release vX.Y.Z, etiqueta vX.Y.Z, empuja el commit y la etiqueta.

El flujo de trabajo de etiquetas verifica que la etiqueta coincida con la versión del crate, crea el lanzamiento de GitHub con la sección del changelog como notas, adjunta binarios por plataforma con sumas de verificación SHA256, publica en crates.io y empuja imágenes ghcr.io/johgirard/mcp-multiplexer etiquetadas latest y vX.Y.Z.

Licencia

MIT. Libre para cualquier uso, incluido comercial — el único requisito es mantener el aviso de copyright.

mcp-multiplexer

Documentación

mcp-multiplexer

Qué hace

Instalación

Configuración

Modo híbrido: expose

OAuth

Claude Code

Cuando cambian las herramientas upstream

Docker

Registro de actividad

Estadísticas

No objetivos

Desarrollo

Lanzamientos

Licencia

Modo híbrido: `expose`