mcp-broker

mcp-broker

mcp-broker es un broker de procesos local para el Protocolo de Contexto de Modelos (MCP) para clientes MCP.

Piense en PgBouncer para MCP: un único punto final local estable frente a muchos servidores MCP ascendentes. El broker gestiona el inicio, la reutilización, la limpieza, la exposición de perfiles, el estado y el enrutamiento seguro de herramientas de los servidores ascendentes.

La idea central es simple: no hacer que cada sesión de agente cargue todas las definiciones de herramientas ascendentes antes de que el usuario solicite una tarea.

Por qué existe esto

Las sesiones de codificación con IA con muchos servidores MCP tienden a acumular los mismos problemas:

• cada configuración de cliente repite la misma lista de servidores MCP
• cada nueva sesión puede iniciar procesos ascendentes duplicados
• OAuth, estado del navegador, archivos locales y manejadores de bases de datos se distribuyen entre las herramientas
• las listas de herramientas sin procesar consumen contexto antes de que comience la tarea
• las cachés de conectores alojados pueden duplicar herramientas MCP locales
• los procesos MCP huérfanos sobreviven después de que las sesiones del cliente finalizan

mcp-broker coloca una pequeña fachada de broker frente a esos servidores ascendentes. No es un constructor de flujos de trabajo alojado; es infraestructura local para mantener a los clientes MCP pequeños, predecibles y bajo un único contrato de configuración.

Client profile
        |
        | one local MCP entry
        v
  mcp-broker-client
        |
        | Unix socket
        v
  mcp-broker-daemon
        |
        | profile gates, namespace routing, status, cleanup
        v
  upstream MCP servers

El cliente ve un pequeño conjunto de herramientas del broker:

broker_search_tools
broker_describe_tool
broker_call_tool
broker_status
broker_close_session

Los MCP ascendentes aún existen. Se descubren y se llaman a través del broker cuando una tarea los necesita.

Reducción de contexto medida

El 2026-05-24, la configuración de Codex medida pasó de muchas definiciones de herramientas MCP sin procesar y de aplicaciones alojadas a una única fachada de broker más una caché de codex_apps podada.

Superficie	Antes	Después	Reducción
Entradas directas de servidor MCP en Codex	11	1	90.91%
Definiciones de herramientas MCP	414	4	99.03%
Definiciones de herramientas de codex_apps alojadas	195	39	80.00%
Definiciones de herramientas combinadas siempre cargadas	609	43	92.94%
Bytes de carga útil de herramientas serializadas combinadas	1,026,171	185,877	81.89%
Tokens de herramientas de o200k_base combinados	276,989	45,281	83.65%

El número del 92.94% es una reducción en el recuento de definiciones de herramientas. El número del 83.65% es una reducción de tokens para cargas útiles de herramientas serializadas canónicas medidas con tiktoken o200k_base.

Consulte docs/context-reduction-measurement.md para ver evidencia y advertencias.

Qué hace

• Ejecuta un único daemon de broker local sobre un socket Unix.
• Expone un shim de cliente stdio ligero a los clientes MCP.
• Inicia servidores MCP ascendentes bajo demanda.
• Reutiliza servidores ascendentes compartidos entre sesiones cuando está configurado.
• Aísla servidores ascendentes por sesión cuando el estado no debe compartirse.
• Asigna herramientas ascendentes a espacios de nombres estables.
• Expone herramientas compactas de búsqueda, descripción, llamada, estado y cierre de sesión vinculado al llamador.
• Aplica presupuestos de herramientas y puertas de exposición a nivel de perfil.
• Bloquea la exposición ascendente mutante a menos que una lista de permitidos de perfil la conceda.
• Almacena el estado de ejecución bajo $HOME/mcp/mcp-broker, fuera del repositorio.
• Renderiza entradas de configuración de clientes MCP con simulación, copia de seguridad y reversión.
• Proporciona flujos de instalación y desinstalación de LaunchAgent para macOS.
• Proporciona flujos de renderizado, instalación, descarga y eliminación de servicios de usuario systemd para Linux.
• Proporciona flujos de renderizado, instalación y eliminación de Tareas Programadas de PowerShell para Windows.
• Incluye pruebas unitarias, de recorrido, en vivo y e2e a través de objetivos de Makefile.

Diferenciadores principales:

• Exposición con ámbito de perfil: cada cliente MCP obtiene una vista configurada de los servidores ascendentes en lugar de todas las herramientas por defecto.
• Puertas de herramientas mutantes: los servidores ascendentes mutantes permanecen ocultos hasta que una lista de permitidos de perfil concede acceso.
• Propiedad del ciclo de vida: los servidores ascendentes compartidos y por sesión son iniciados, supervisados, detenidos y recolectados por el broker.
• Comprobaciones de paridad de clientes: los perfiles renderizados se pueden validar a través de la misma fachada compacta del broker antes de aplicar la configuración.

Para quién es esto

Use mcp-broker si usted:

• usa Codex, Claude Code, CLI de AGY u otros clientes MCP
• tiene más herramientas MCP de las que desea en cada sesión
• necesita servidores MCP locales compartidos sin inicio de procesos duplicados
• quiere un solo lugar para el estado de OAuth, estado del navegador, sockets, registros y limpieza
• necesita perfiles por cliente en lugar de la misma lista de herramientas en todas partes
• quiere una pequeña fachada de broker en lugar de volcados de herramientas ascendentes sin procesar

Este repositorio no es un plano de control MCP empresarial. Es infraestructura local de escritorio para flujos de trabajo de desarrollador-agente.

Estado actual

Implementado:

• Carga de configuración YAML desde config/broker.private.yaml, creada a partir de config/broker.example.yaml.
• Validación estricta del contrato YAML para bloques de tiempo de ejecución, clientes, perfiles, servidores ascendentes y políticas.
• Validación pública de esquema JSON a través de config/broker.schema.json.
• Derivación de la ruta de tiempo de ejecución desde runtime.root.
• Asignación de espacios de nombres de herramientas a partir de prefijos de servidores ascendentes configurados.
• Gestión del ciclo de vida de subprocesos ascendentes locales y limpieza de grupos de procesos.
• Daemon de broker sobre socket Unix.
• Shim de cliente MCP y renderizadores para perfiles de clientes MCP configurados, incluidos Codex, Claude y AGY.
• Renderizado de perfil AGY a .gemini/config/mcp_config.json, incluida su política de servidores permitidos MCP.
• Renderizado de configuración de cliente en modo simulación, copias de seguridad en el momento de la aplicación y reversión.
• Scripts de renderizado e instalación de LaunchAgent con valores predeterminados de simulación.
• Fachada compacta del broker para búsqueda, descripción, llamada, estado y cierre de sesión vinculado al llamador.
• Validación de perfiles a partir de sondas de humo YAML.
• Comprobaciones de paridad de descubrimiento entre perfiles de cliente compactos.
• Puertas de calidad públicas y de mantenedores a través de objetivos de Makefile.
• Contratos de salvaguarda de tiempo de ejecución compartido a través de prueba E2E P3.8 mientras la ejecución alojada permanece deshabilitada por defecto.

Estado de cableado:

• Codex está conectado a través del broker.
• Claude está conectado a través del broker después de la validación de perfil y la aceptación manual de /mcp.
• AGY está conectado a través del broker renderizando .gemini/config/mcp_config.json.

Estado de publicación pública:

• El repositorio está diseñado para permanecer seguro para el público.
• El inventario ascendente privado, las rutas de cuentas, el estado de OAuth, los secretos, los sockets, los registros y las configuraciones de cliente generadas permanecen fuera de git.
• Los metadatos de versión estable se validan mediante make release-version-check; la prueba de publicación se rastrea en docs/distribution.md.
• El soporte de imágenes Docker está disponible para configuraciones compatibles con contenedores. El envío al Catálogo MCP de Docker aún requiere revisión de Docker.
• Los metadatos de MCPB están presentes en mcpb/manifest.json para revisión de directorio local.

Consulte ROADMAP.md para el trabajo de publicación orientado al público.

Arquitectura

mcp-broker tiene tres capas de tiempo de ejecución:

Capa	Responsabilidad
Shim de cliente	Presenta una entrada de servidor MCP stdio a cada cliente MCP y reenvía JSON-RPC a través del socket del broker.
Daemon de broker	Posee puertas de perfil, enrutamiento de espacios de nombres, ciclo de vida ascendente, estado, registro y limpieza.
Servidores MCP ascendentes	Se ejecutan como conectores stdio, HTTP, HTTP transmisible o SSE configurados con política de procesos compartida o por sesión.

El archivo de configuración es el contrato. Los perfiles deciden la exposición, los servidores ascendentes definen el transporte y el comportamiento del ciclo de vida, y las sondas de humo definen llamadas de lectura seguras para la validación.

Comparación

Enfoque	Mejor ajuste	Compensación
Configuración MCP de cliente sin procesar	Configuraciones pequeñas con pocas herramientas.	Cada sesión carga la lista completa de herramientas y cada cliente repite la configuración.
Proxy MCP simple	Reenvío de un servidor a un cliente.	No posee el ciclo de vida ascendente, los presupuestos de perfil ni la limpieza entre clientes.
Conectores de aplicaciones alojadas	Herramientas SaaS gestionadas por el proveedor del cliente.	El estado MCP local y la paridad entre clientes permanecen fuera del control del usuario.
mcp-broker	Desarrolladores locales con muchos MCP ascendentes en varios clientes MCP.	Agrega un daemon local y un contrato de configuración que deben instalarse y supervisarse.

Capturas de pantalla o GIF

El flujo de inicio rápido debería verse así:

make config-init
make config-validate
make broker-status
make codex-facade-smoke

En un cliente MCP, /mcp debería mostrar una entrada de mcp-broker. Use broker_status para inspeccionar el estado ascendente visible en el perfil.

Inicio rápido

Requisitos previos:

• macOS con launchctl para uso de LaunchAgent.
• Python 3.10 o más reciente disponible como python3.
• make.
• Node.js y npx para servidores MCP ascendentes basados en npm.
• Un clon de este repositorio.

Instalaciones de paquetes:

pipx install mcp-broker
uv tool install mcp-broker
brew tap ${HOMEBREW_TAP_REF}
brew install mcp-broker

Homebrew instala los mismos scripts de consola que el paquete de Python. Las instalaciones de paquetes no escriben la configuración del cliente MCP; el cableado del cliente sigue siendo una acción explícita del Makefile.

Docker es para configuraciones compatibles con contenedores:

docker build -t mcp-broker:local .
docker run --rm -i mcp-broker:local

Los clientes stdio locales y las instalaciones de estilo MCPB usan el ciclo de vida propiedad del paquete:

mcp-broker stdio --init-if-missing

Cree el venv local, instale las dependencias y verifique el diseño del tiempo de ejecución:

make setup

Cree la configuración privada a partir de la plantilla pública:

make config-init

config-init crea el directorio de destino cuando es necesario y copia la plantilla pública como punto de partida. No importa el inventario MCP local, las rutas de usuario ni los secretos.

Edite config/broker.private.yaml para los servidores ascendentes locales. Mantenga los valores secretos fuera de la configuración. Use nombres de variables de entorno o archivos bajo:

$HOME/mcp/mcp-broker/secrets/

Ejecute la puerta de calidad:

make quality-gate

Valide el contrato YAML configurado:

make config-validate

Inicie el broker:

make broker-start

Compruebe el estado:

make broker-status

Para el flujo de instalación completo, consulte docs/install.md. Para un flujo de adopción de clon a ejecución, consulte docs/adoption-guide.md#clone-to-running-path. Para los límites de tiempo de ejecución compartido, consulte docs/shared-runtime-guardrails.md. La prueba E2E P3.8 cubre el aislamiento de inquilinos, la denegación de autorización, la denegación de cuotas, la afinidad de sesión, los eventos de auditoría, la reversión, el modo degradado, el enrutamiento solo local y el enrutamiento elegible compartido. La ejecución alojada sigue sin ser compatible con el broker local público.

Diseño del tiempo de ejecución

Raíz de tiempo de ejecución predeterminada:

$HOME/mcp/mcp-broker/
|- backups/
|- logs/
|- renders/
|- run/
|- secrets/
|- sockets/
`- state/
   `- upstreams/

Los archivos de tiempo de ejecución no son archivos del repositorio. El estado de OAuth ascendente, el estado del navegador, los archivos secretos, los sockets, los registros, las configuraciones de cliente renderizadas, las copias de seguridad y el estado del daemon pertenecen a la raíz de tiempo de ejecución.

Consulte docs/runtime-layout.md.

Cableado del cliente

Haga una copia de seguridad de una configuración de cliente:

make config-backup CLIENT=codex

Renderizado en modo simulación:

make config-render CLIENT=codex CONFIG_RENDER_APPLY=0

Aplique después de revisar el archivo renderizado bajo $HOME/mcp/mcp-broker/renders/:

make config-render CLIENT=codex CONFIG_RENDER_APPLY=1

Reversión:

make config-rollback CLIENT=codex

Use CLIENT=claude o CLIENT=agy después de que esa prueba de humo de perfil pase y ese cliente esté destinado a usar el broker. Para nuevos clientes MCP basados en JSON, genere un bloque inicial:

make profile-snippet NEW_PROFILE=local-client NEW_CLIENT_FORMAT=mcp-settings-json

Consulte docs/add-profile.md para el flujo completo de nuevo perfil.

Fachada compacta del broker

La fachada compacta mantiene pequeños los perfiles orientados al chat:

Herramienta	Propósito
broker_search_tools	Busca herramientas ascendentes configuradas por consulta. Los resultados incluyen nombre, descripción, servidor ascendente, propósito, etiquetas y bandera mutante; el pesado inputSchema se omite y se obtiene bajo demanda desde broker_describe_tool.
broker_describe_tool	Devuelve el esquema y los metadatos de una herramienta ascendente.
broker_call_tool	Llama a una herramienta ascendente a través del enrutamiento del broker. Acepta un projection opcional ({"paths": [...], "max_array_items": N}) que recorta la respuesta del lado del servidor antes de que llegue al cliente.
broker_status	Muestra el estado ascendente visible en el perfil, las sondas de autenticación pasiva y los últimos errores sin iniciar herramientas.
broker_close_session	Libera los procesos ascendentes por sesión propiedad del llamador sin detener los servidores ascendentes compartidos ni otra sesión de cliente.

Codex /mcp muestra la única entrada de mcp-broker por diseño. La visibilidad por servidor ascendente, el estado y la ruta del socket provienen de broker_status.

Perfiles y seguridad

Los perfiles deciden qué servidores ascendentes puede ver y llamar un cliente.

Conceptos admitidos:

• max_tools protege a los clientes de listas de herramientas enormes.
• compact_tools_enabled expone herramientas de fachada del broker en lugar de herramientas upstream sin procesar.
• broker_tool_name_style adapta los nombres de la fachada del broker para clientes que no pueden mostrar nombres de herramientas con puntos.
• mcp_allowed_servers renderiza la configuración del cliente para clientes MCP que requieren una lista de permitidos de servidores explícita.
• allow_mutating_upstreams es necesario antes de que un upstream mutante pueda ser expuesto.
• El modo shared reutiliza un proceso upstream donde el estado de cuenta compartido es aceptable.
• El modo per_session aísla el estado upstream por sesión de cliente.
• El modo per_call inicia un proceso stdio nuevo para cada llamada de herramienta u operación de listado de herramientas, y luego detiene ese proceso antes de regresar.
• El modo disabled mantiene registros de compatibilidad sin exponer el upstream.

Los informes de estado active_call_count para operaciones per_call en curso, incluido el descubrimiento de herramientas. Vuelve a cero después de la limpieza por éxito, fallo o tiempo de espera. Este conteo es separado de session_count y no es un conteo de hilos guardados. Leer el estado no inicia un upstream; los upstreams ocultos por perfil permanecen ocultos.

Las superficies protegidas como OAuth, estado del navegador, raíces del sistema de archivos y bases de datos requieren configuración y validación explícitas. Los ejemplos públicos permanecen deshabilitados o basados en marcadores de posición.

Consulta docs/security-review.md y docs/upstream-compatibility-matrix.md. Para una lista de verificación de seguridad más profunda, consulta docs/safety.md.

Contrato de configuración

La plantilla pública es config/broker.example.yaml. El JSON Schema correspondiente es config/broker.schema.json.

Secciones de nivel superior compatibles:

schema_version: 1
runtime: {}
broker: {}
profiles: {}
clients: {}
upstreams: {}

El cargador rechaza claves desconocidas. Los marcadores de posición de tiempo de ejecución como {runtime.root}, {runtime.state_dir} y {runtime.secrets_dir} se pueden usar en el comando upstream, argumentos, directorio de trabajo y rutas de archivos de entorno.

make config-validate verifica el CONFIG_PATH seleccionado contra el JSON Schema público primero, luego ejecuta el cargador de tiempo de ejecución para que las reglas semánticas se apliquen desde la misma ruta de código que usa el broker.

Cada upstream habilitado expuesto a un perfil debe definir una sonda de humo segura:

smoke:
  query: read example graph
  tool: example-store.read_graph
  arguments: {}
  call: true

make profile-validation PROFILE=<profile> valida cada upstream habilitado visible para ese perfil a través de broker_status, broker_search_tools, broker_describe_tool y el broker_call_tool seguro configurado.

Aceptación del operador de Codex

Las pruebas propiedad del repositorio validan el comportamiento del broker a través del shim de cliente local. La última verificación específica de Codex debe ejecutarse dentro de una sesión activa de Codex porque es donde existen las herramientas de envoltura MCP diferidas.

Genera los pasos de aceptación actuales desde YAML:

make codex-deferred-acceptance

El objetivo lee las sondas smoke configuradas e imprime las llamadas exactas de envoltura mcp__mcp_broker__ para búsqueda, descripción y llamada segura. No invoca Codex, no llama a una sesión LLM externa y no es parte de make quality-gate.

Consulta docs/codex-deferred-tool-acceptance.md.

LaunchAgent

Renderizar sin escribir:

make launchagent-install

Aplicar y cargar:

make launchagent-install LAUNCHAGENT_APPLY=1
make launchagent-load
make broker-status

Descargar o eliminar:

make launchagent-unload
make launchagent-uninstall LAUNCHAGENT_APPLY=1

systemd

La instalación de servicio de usuario de Linux usa el mismo contrato de raíz de tiempo de ejecución y ruta de configuración:

make systemd-install
make systemd-install SYSTEMD_APPLY=1
make systemd-load

Para instalaciones de paquetes, establece MCP_BROKER_DAEMON_COMMAND a la ruta del daemon instalado antes de aplicar el servicio.

Windows

El inicio de Windows usa comandos de Tarea Programada de PowerShell con el mismo contrato de raíz de tiempo de ejecución y ruta de configuración:

make windows-install
make windows-install WINDOWS_APPLY=1
make windows-load

Elimínalo con:

make windows-unload
make windows-uninstall WINDOWS_APPLY=1

Puertas de prueba y lanzamiento

Ejecuta todos los niveles de prueba:

make test

Ejecuta la puerta de calidad pública:

make quality-gate

La puerta de cobertura usa cobertura de líneas y ramas para el código fuente de Python.

Ejecuta la puerta de lanzamiento al preparar una etiqueta:

make release-gate

release-gate ejecuta verificaciones de paquete, humo y mutación. La mutación recibe un conteo de hijos con alcance de lanzamiento derivado de LOCAL_CPU_BUDGET y RELEASE_GATE_JOBS, por lo que no toma el presupuesto completo de CPU mientras otros hijos de lanzamiento se ejecutan. La mutación ejecuta pruebas unitarias y de viaje públicas al final y escribe var/quality/mutation_stats.json con conteos totales, puntuación y entradas blocked_by_file clasificadas. En macOS, la puerta de lanzamiento ejecuta la mutación dentro de un contenedor Linux para evitar fallos locales de fork de mutmut. Las pruebas E2E permanecen en make quality-gate.

Ejecuta verificaciones de humo y limpieza de tiempo de ejecución:

make config-validate
make broker-smoke
make broker-stop
make broker-reap
make doctor
make release-smoke

El lanzamiento o la aplicación de configuración del cliente deben esperar por:

• make quality-gate
• make config-validate
• make broker-smoke
• renderizado de configuración de prueba para cada cliente previsto
• prueba de reversión
• make release-smoke
• make release-gate antes de etiquetar
• make doctor sin recursos obsoletos propiedad del broker

Consulta docs/release-checklist.md.

Comandos públicos

Estos objetivos usan este repositorio más los requisitos declarados de Python y Node:

Para contribuciones de código fuente, instala gitleaks en PATH y ejecuta make hooks-install en cada checkout. El hook de pre-commit rastreado requiere un escaneo de secretos en etapa con redacción, luego ejecuta pruebas afectadas de nivel de commit a través de Make. Herramientas de escáner faltantes, alcance en etapa vacío y fallos de escaneo o prueba bloquean el commit. GITLEAKS y PYTHON seleccionan el escáner y el intérprete del mantenedor. La instalación usa la configuración específica del worktree de Git y rechaza hooks existentes desconocidos o configuraciones comunes de core.worktree/bare que necesitan migración. No se inicia ningún flujo de trabajo alojado.

make setup
make config-init
make test
make test-unit
make test-journey
make test-live
make test-e2e
make test-cov
make precommit
make quality-gate
make release-gate
make config-validate
make broker-smoke
make broker-start
make broker-status
make broker-stop
make broker-reap
make doctor
make config-backup
make codex-app-policy
make config-render
make config-rollback
make tools-count
make facade-smoke
make codex-facade-smoke
make claude-facade-smoke
make agy-facade-smoke
make profile-validation
make codex-profile-validation
make claude-profile-validation
make agy-profile-validation
make discovery-parity
make codex-claude-discovery-parity
make codex-deferred-acceptance
make launchagent-install
make launchagent-load
make launchagent-unload
make launchagent-uninstall
make systemd-install
make systemd-load
make systemd-unload
make systemd-uninstall
make windows-install
make windows-load
make windows-unload
make windows-uninstall
make linux-container-smoke
make windows-powershell-smoke
make release-smoke
make mutation
make mutation-linux

make quality-gate es local al repositorio. No llama a scripts personales fuera de este repositorio.

make codex-deferred-acceptance es solo para mantenedores. No invoca Codex ni una sesión LLM externa. Lee las mismas sondas YAML smoke e imprime las llamadas exactas de envoltura diferida mcp__mcp_broker__ para ejecutar dentro de una sesión activa de Codex. Consulta docs/codex-deferred-tool-acceptance.md.

Árbol del proyecto

mcp-broker/
|- .gitignore
|- Makefile
|- README.md
|- pyproject.toml
|- requirements.txt
|- config/
|  |- broker.example.yaml
|  |- broker.private.yaml        # local, ignored by git
|  `- broker.schema.json
|- docs/
|- registry/
|- scripts/
|  `- check_mutation_stats.py
|- src/
|  `- mcp_broker/
|- tests/
|  |- unit/
|  |- journey/
|  |- live/
|  |- e2e/
|  `- support/
`- var/                         # tracked skeleton; generated contents ignored

Los informes generados permanecen bajo var/, especialmente var/coverage/, var/test-logs/ y var/quality/.

Documentación

• SECURITY.md
• CONTRIBUTING.md
• ROADMAP.md
• docs/install.md
• docs/add-profile.md
• docs/migration.md
• docs/adoption-guide.md
• docs/comparison.md
• docs/distribution.md
• docs/github-publication.md
• docs/community-launch.md
• docs/auth-recipes.md
• docs/architecture.md
• docs/protocol.md
• docs/runtime-layout.md
• docs/safety.md
• docs/security-review.md
• docs/upstream-compatibility-matrix.md
• docs/codex-deferred-tool-acceptance.md
• docs/context-reduction-measurement.md
• docs/mutation-testing.md
• docs/release-checklist.md
• docs/troubleshooting.md

Reglas de diseño

• Mantén las definiciones upstream en la configuración central.
• Mantén el estado de tiempo de ejecución bajo $HOME/mcp/mcp-broker.
• Mantén el inventario upstream privado en config/broker.private.yaml, que es ignorado por git.
• Mantén los valores secretos fuera de la configuración y el código fuente.
• No codifiques rutas personales en código fuente, pruebas, documentación o configuración pública.
• Ejecuta operaciones de compilación, prueba, tiempo de ejecución y configuración a través del Makefile.