mcp-broker

mcp-broker

mcp-broker é um broker de processos local para o Model Context Protocol, voltado para clientes MCP.

Pense no PgBouncer para MCP: um endpoint local estável na frente de vários servidores MCP upstream. O broker é dono da inicialização, reutilização, limpeza, exposição de perfis, status e roteamento seguro de ferramentas dos upstreams.

A ideia central é simples: não fazer cada sessão de agente carregar todas as definições de ferramentas upstream antes de o usuário pedir uma tarefa.

Por que isso existe

Sessões de codificação com IA com muitos servidores MCP tendem a acumular os mesmos problemas:

• cada configuração de cliente repete a mesma lista de servidores MCP
• cada nova sessão pode iniciar processos upstream duplicados
• OAuth, estado do navegador, arquivos locais e conexões de banco de dados espalhados entre ferramentas
• listas brutas de ferramentas consomem contexto antes de a tarefa começar
• caches de conectores hospedados podem duplicar ferramentas MCP locais
• processos MCP órfãos sobrevivem após o encerramento das sessões do cliente

mcp-broker coloca uma pequena fachada de broker na frente desses upstreams. Não é um construtor de fluxos de trabalho hospedado; é infraestrutura local para manter clientes MCP enxutos, previsíveis e sob um único contrato de configuração.

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

O cliente vê um pequeno conjunto de ferramentas do broker:

broker_search_tools
broker_describe_tool
broker_call_tool
broker_status
broker_close_session

Os MCPs upstream ainda existem. Eles são descobertos e chamados por meio do broker quando uma tarefa precisa deles.

Redução de contexto medida

Em 2026-05-24, a configuração medida do Codex passou de muitas definições brutas de ferramentas MCP e de aplicativos hospedados para uma única fachada de broker mais um cache podado de codex_apps.

Superfície	Antes	Depois	Redução
Entradas diretas de servidor MCP no Codex	11	1	90,91%
Definições de ferramentas MCP	414	4	99,03%
Definições de ferramentas hospedadas codex_apps	195	39	80,00%
Definições de ferramentas sempre carregadas, combinadas	609	43	92,94%
Bytes de payload serializado de ferramentas, combinados	1.026.171	185.877	81,89%
Tokens de ferramentas o200k_base combinados	276.989	45.281	83,65%

O número de 92,94% é uma redução na contagem de definições de ferramentas. O número de 83,65% é uma redução de tokens para payloads canônicos serializados de ferramentas, medidos com tiktoken o200k_base.

Veja docs/context-reduction-measurement.md para evidências e ressalvas.

O que ele faz

• Executa um daemon de broker local em um socket Unix.
• Expõe um shim de cliente stdio leve para clientes MCP.
• Inicia servidores MCP upstream sob demanda.
• Reutiliza upstreams compartilhados entre sessões quando configurado.
• Isola upstreams por sessão quando o estado não deve ser compartilhado.
• Mapeia ferramentas upstream em namespaces estáveis.
• Expõe ferramentas compactas de busca, descrição, chamada, status e encerramento de sessão vinculado ao chamador.
• Aplica orçamentos de ferramentas e portões de exposição por perfil.
• Bloqueia exposição mutável de upstreams, a menos que uma allowlist de perfil conceda acesso.
• Armazena estado de runtime em $HOME/mcp/mcp-broker, fora do repositório.
• Renderiza entradas de configuração de clientes MCP com dry-run, backup e rollback.
• Fornece fluxos de instalação e desinstalação de LaunchAgent para macOS.
• Fornece fluxos de renderização, instalação, descarregamento e remoção de serviço systemd para Linux.
• Fornece fluxos de renderização, instalação e remoção de Tarefa Agendada do PowerShell para Windows.
• Inclui testes de unidade, jornada, ao vivo e e2e por meio de alvos do Makefile.

Diferenciadores principais:

• Exposição por perfil: cada cliente MCP recebe uma visão configurada dos upstreams, em vez de todas as ferramentas por padrão.
• Portões de ferramentas mutáveis: upstreams mutáveis permanecem ocultos até que uma allowlist de perfil conceda acesso.
• Propriedade do ciclo de vida: upstreams compartilhados e por sessão são iniciados, monitorados, interrompidos e coletados pelo broker.
• Verificações de paridade do cliente: perfis renderizados podem ser validados pela mesma fachada compacta do broker antes de a configuração ser aplicada.

Para quem é isso

Use mcp-broker se você:

• usa Codex, Claude Code, CLI AGY ou outros clientes MCP
• tem mais ferramentas MCP do que deseja em cada sessão
• precisa de servidores MCP locais compartilhados sem inicialização duplicada de processos
• quer um único lugar para estado OAuth, estado do navegador, sockets, logs e limpeza
• precisa de perfis por cliente em vez da mesma lista de ferramentas em todos os lugares
• quer uma pequena fachada de broker em vez de despejos brutos de ferramentas upstream

Este repositório não é um plano de controle MCP empresarial. É infraestrutura local de desktop para fluxos de trabalho de agente-desenvolvedor.

Status atual

Implementado:

• Carregamento de configuração YAML de config/broker.private.yaml, criado a partir de config/broker.example.yaml.
• Validação estrita de contrato YAML para blocos de runtime, clientes, perfis, upstreams e política.
• Validação pública de JSON Schema por meio de config/broker.schema.json.
• Derivação de caminho de runtime a partir de runtime.root.
• Mapeamento de namespace de ferramentas a partir de prefixos de upstream configurados.
• Gerenciamento do ciclo de vida de subprocessos upstream locais e limpeza de grupo de processos.
• Daemon de broker em socket Unix.
• Shim de cliente MCP e renderizadores para perfis de clientes MCP configurados, incluindo Codex, Claude e AGY.
• Renderização de perfil AGY para .gemini/config/mcp_config.json, incluindo sua política de servidores permitidos MCP.
• Renderização de configuração de cliente com dry-run, backups no momento da aplicação e rollback.
• Scripts de renderização e instalação de LaunchAgent com padrões de dry-run.
• Fachada compacta do broker para busca, descrição, chamada, status e encerramento de sessão vinculado ao chamador.
• Validação de perfil a partir de sondas de fumaça YAML.
• Verificações de paridade de descoberta entre perfis de cliente compactos.
• Portões de qualidade públicos e de mantenedores por meio de alvos do Makefile.
• Contratos de proteção de runtime compartilhado por meio de prova E2E P3.8, enquanto a execução hospedada permanece desabilitada por padrão.

Status de integração:

• Codex está integrado por meio do broker.
• Claude está integrado por meio do broker após validação de perfil e aceitação manual de /mcp.
• AGY está integrado por meio do broker ao renderizar .gemini/config/mcp_config.json.

Status de lançamento público:

• O repositório foi projetado para permanecer seguro para o público.
• Inventário upstream privado, caminhos de conta, estado OAuth, segredos, sockets, logs e configurações de cliente geradas permanecem fora do git.
• Metadados de versão estável são validados por make release-version-check; a prova de publicação é rastreada em docs/distribution.md.
• Suporte a imagem Docker está disponível para configurações amigáveis a contêineres. O envio ao Catálogo MCP do Docker ainda requer revisão do Docker.
• Metadados MCPB estão presentes em mcpb/manifest.json para revisão local de diretório.

Veja ROADMAP.md para o trabalho de lançamento voltado ao público.

Arquitetura

mcp-broker tem três camadas de runtime:

Camada	Responsabilidade
Shim de cliente	Apresenta uma entrada de servidor MCP stdio para cada cliente MCP e encaminha JSON-RPC pelo socket do broker.
Daemon do broker	É dono dos portões de perfil, roteamento de namespace, ciclo de vida de upstream, status, logs e limpeza.
Servidores MCP upstream	Executam como conectores stdio, HTTP, HTTP transmissível ou SSE configurados, com política de processo compartilhada ou por sessão.

O arquivo de configuração é o contrato. Perfis decidem a exposição, upstreams definem transporte e comportamento de ciclo de vida, e sondas de fumaça definem chamadas de leitura seguras para validação.

Comparação

Abordagem	Melhor para	Tradeoff
Configuração bruta de cliente MCP	Configurações pequenas com poucas ferramentas.	Cada sessão carrega a lista completa de ferramentas e cada cliente repete a configuração.
Proxy MCP simples	Encaminhar um servidor para um cliente.	Não é dono do ciclo de vida de upstream, orçamentos de perfil ou limpeza entre clientes.
Conectores de aplicativos hospedados	Ferramentas SaaS gerenciadas pelo provedor do cliente.	Estado MCP local e paridade entre clientes permanecem fora do controle do usuário.
mcp-broker	Desenvolvedores locais com muitos MCPs upstream em vários clientes MCP.	Adiciona um daemon local e um contrato de configuração que precisam ser instalados e monitorados.

Capturas de tela ou GIF

O fluxo de início rápido deve ser assim:

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

Em um cliente MCP, /mcp deve mostrar uma entrada mcp-broker. Use broker_status para inspecionar o estado upstream visível ao perfil.

Início rápido

Pré-requisitos:

• macOS com launchctl para uso de LaunchAgent.
• Python 3.10 ou mais recente disponível como python3.
• make.
• Node.js e npx para servidores MCP upstream baseados em npm.
• Um clone deste repositório.

Instalações de pacotes:

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

O Homebrew instala os mesmos scripts de console que o pacote Python. As instalações de pacotes não gravam configuração de cliente MCP; a integração do cliente permanece uma ação explícita do Makefile.

Docker é para configurações amigáveis a contêineres:

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

Clientes stdio locais e instalações no estilo MCPB usam o ciclo de vida de propriedade do pacote:

mcp-broker stdio --init-if-missing

Crie o venv local, instale as dependências e verifique o layout do runtime:

make setup

Crie a configuração privada a partir do modelo público:

make config-init

config-init cria o diretório de destino quando necessário e copia o modelo público como ponto de partida. Ele não importa inventário MCP local, caminhos de usuário ou segredos.

Edite config/broker.private.yaml para upstreams locais. Mantenha valores secretos fora da configuração. Use nomes de variáveis de ambiente ou arquivos em:

$HOME/mcp/mcp-broker/secrets/

Execute o portão de qualidade:

make quality-gate

Valide o contrato YAML configurado:

make config-validate

Inicie o broker:

make broker-start

Verifique o status:

make broker-status

Para o fluxo completo de instalação, veja docs/install.md. Para um fluxo de adoção do clone à execução, veja docs/adoption-guide.md#clone-to-running-path. Para limites de runtime compartilhado, veja docs/shared-runtime-guardrails.md. A prova E2E P3.8 cobre isolamento de locatário, negação de autorização, negação de cota, afinidade de sessão, eventos de auditoria, rollback, modo degradado, roteamento somente local e roteamento elegível compartilhado. A execução hospedada permanece sem suporte no broker local público.

Layout do runtime

Raiz padrão do runtime:

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

Arquivos de runtime não são arquivos do repositório. Estado OAuth de upstream, estado do navegador, arquivos secretos, sockets, logs, configurações de cliente renderizadas, backups e estado do daemon pertencem à raiz do runtime.

Veja docs/runtime-layout.md.

Integração do cliente

Faça backup de uma configuração de cliente:

make config-backup CLIENT=codex

Renderização com dry-run:

make config-render CLIENT=codex CONFIG_RENDER_APPLY=0

Aplique após revisar o arquivo renderizado em $HOME/mcp/mcp-broker/renders/:

make config-render CLIENT=codex CONFIG_RENDER_APPLY=1

Rollback:

make config-rollback CLIENT=codex

Use CLIENT=claude ou CLIENT=agy depois que a sonda de fumaça desse perfil passar e esse cliente for destinado a usar o broker. Para novos clientes MCP baseados em JSON, gere um bloco inicial:

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

Veja docs/add-profile.md para o fluxo completo de novo perfil.

Fachada compacta do broker

A fachada compacta mantém perfis voltados ao chat enxutos:

Ferramenta	Propósito
broker_search_tools	Busca ferramentas upstream configuradas por consulta. Os resultados trazem nome, descrição, upstream, propósito, tags e sinalizador de mutação; o pesado inputSchema é omitido e buscado sob demanda de broker_describe_tool.
broker_describe_tool	Retorna schema e metadados de uma ferramenta upstream.
broker_call_tool	Chama uma ferramenta upstream por meio do roteamento do broker. Aceita um projection opcional ({"paths": [...], "max_array_items": N}) que reduz a resposta no lado do servidor antes de chegar ao cliente.
broker_status	Mostra estado upstream visível ao perfil, sondas de autenticação passivas e últimos erros sem iniciar ferramentas.
broker_close_session	Libera processos upstream por sessão de propriedade do chamador sem interromper upstreams compartilhados ou outra sessão de cliente.

O /mcp do Codex mostra a única entrada mcp-broker por design. Visibilidade por upstream, status e caminho do socket vêm de broker_status.

Perfis e segurança

Perfis decidem quais upstreams um cliente pode ver e chamar.

Conceitos suportados:

• max_tools protege os clientes de listas de ferramentas enormes.
• compact_tools_enabled expõe ferramentas de fachada do broker em vez de ferramentas upstream brutas.
• broker_tool_name_style adapta os nomes das fachadas do broker para clientes que não conseguem exibir nomes de ferramentas com pontos.
• mcp_allowed_servers renderiza as configurações do cliente para clientes MCP que exigem uma lista de permissões explícita de servidores.
• allow_mutating_upstreams é necessário antes que um upstream mutável possa ser exposto.
• O modo shared reutiliza um processo upstream onde o estado de conta compartilhado é aceitável.
• O modo per_session isola o estado upstream por sessão de cliente.
• O modo per_call inicia um novo processo stdio para cada chamada de ferramenta ou operação de listagem de ferramentas e, em seguida, interrompe esse processo antes de retornar.
• O modo disabled mantém registros de compatibilidade sem expor o upstream.

Os relatórios de status active_call_count para operações per_call em andamento, incluindo descoberta de ferramentas. Ele retorna a zero após sucesso, falha ou limpeza por tempo limite. Essa contagem é separada de session_count e não é uma contagem de threads salvos. Ler o status não inicia um upstream; upstreams ocultos por perfil permanecem ocultos.

Superfícies protegidas, como OAuth, estado do navegador, raízes do sistema de arquivos e bancos de dados, exigem configuração e validação explícitas. Exemplos públicos permanecem desabilitados ou baseados em espaços reservados.

Consulte docs/security-review.md e docs/upstream-compatibility-matrix.md. Para uma lista de verificação de segurança mais aprofundada, consulte docs/safety.md.

Contrato de configuração

O modelo público é config/broker.example.yaml. O JSON Schema correspondente é config/broker.schema.json.

Seções de nível superior suportadas:

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

O carregador rejeita chaves desconhecidas. Espaços reservados de tempo de execução, como {runtime.root}, {runtime.state_dir} e {runtime.secrets_dir}, podem ser usados no comando upstream, argumentos, diretório de trabalho e caminhos de arquivo de ambiente.

make config-validate verifica o CONFIG_PATH selecionado contra o JSON Schema público primeiro e, em seguida, executa o carregador de tempo de execução para que as regras semânticas sejam aplicadas a partir do mesmo caminho de código que o broker usa.

Cada upstream habilitado exposto a um perfil deve definir uma sonda de fumaça segura:

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

make profile-validation PROFILE=<profile> valida cada upstream habilitado visível para esse perfil por meio de broker_status, broker_search_tools, broker_describe_tool e o broker_call_tool seguro configurado.

Aceitação do operador Codex

Testes de propriedade do repositório validam o comportamento do broker por meio do shim de cliente local. A última verificação específica do Codex precisa ser executada dentro de uma sessão Codex ativa, porque é onde existem as ferramentas de wrapper MCP adiadas.

Gere as etapas de aceitação atuais a partir do YAML:

make codex-deferred-acceptance

O destino lê as sondas smoke configuradas e imprime as chamadas exatas do wrapper mcp__mcp_broker__ para busca, descrição e chamada segura. Ele não invoca o Codex, não chama uma sessão LLM externa e não faz parte de make quality-gate.

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

LaunchAgent

Renderizar sem gravar:

make launchagent-install

Aplicar e carregar:

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

Descarregar ou remover:

make launchagent-unload
make launchagent-uninstall LAUNCHAGENT_APPLY=1

systemd

A instalação do serviço de usuário Linux usa o mesmo contrato de raiz de tempo de execução e caminho de configuração:

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

Para instalações de pacotes, defina MCP_BROKER_DAEMON_COMMAND para o caminho do daemon instalado antes de aplicar o serviço.

Windows

A inicialização do Windows usa comandos do PowerShell Scheduled Task com o mesmo contrato de raiz de tempo de execução e caminho de configuração:

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

Remova com:

make windows-unload
make windows-uninstall WINDOWS_APPLY=1

Portões de teste e lançamento

Execute todas as camadas de teste:

make test

Execute o portão de qualidade pública:

make quality-gate

O portão de cobertura usa cobertura de linha e ramo para código-fonte Python.

Execute o portão de lançamento ao preparar uma tag:

make release-gate

release-gate executa verificações de pacote, fumaça e mutação. A mutação recebe uma contagem de filhos com escopo de lançamento derivada de LOCAL_CPU_BUDGET e RELEASE_GATE_JOBS, portanto, não consome todo o orçamento de CPU enquanto outros filhos de lançamento são executados. A mutação executa testes públicos de unidade e jornada por último e grava var/quality/mutation_stats.json com contagens totais, pontuação e entradas blocked_by_file classificadas. No macOS, o portão de lançamento executa a mutação dentro de um contêiner Linux para evitar falhas locais de fork do mutmut. Os testes E2E permanecem em make quality-gate.

Execute verificações de fumaça e limpeza de tempo de execução:

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

O lançamento ou a aplicação de configuração do cliente deve aguardar:

• make quality-gate
• make config-validate
• make broker-smoke
• renderização de configuração de simulação para cada cliente pretendido
• teste de reversão
• make release-smoke
• make release-gate antes da marcação
• make doctor sem recursos obsoletos de propriedade do broker

Consulte docs/release-checklist.md.

Comandos públicos

Esses destinos usam este repositório mais os pré-requisitos declarados de Python e Node:

Para contribuições de código-fonte, instale gitleaks no PATH e execute make hooks-install em cada checkout. O hook de pré-confirmação rastreado requer uma verificação de segredo preparado com redação e, em seguida, executa testes afetados da camada de confirmação por meio do Make. Ferramentas de scanner ausentes, escopo preparado vazio e falhas de verificação ou teste bloqueiam a confirmação. GITLEAKS e PYTHON selecionam o scanner e o intérprete do mantenedor. A instalação usa a configuração específica do worktree do Git e recusa hooks existentes desconhecidos ou configurações comuns de core.worktree/bare que precisam de migração. Nenhum fluxo de trabalho hospedado é iniciado.

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 é local ao repositório. Ele não chama scripts pessoais fora deste repositório.

make codex-deferred-acceptance é somente para mantenedores. Ele não invoca o Codex ou uma sessão LLM externa. Ele lê as mesmas sondas YAML smoke e imprime as chamadas exatas do wrapper adiado mcp__mcp_broker__ para executar dentro de uma sessão Codex ativa. Consulte docs/codex-deferred-tool-acceptance.md.

Árvore do projeto

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

Os relatórios gerados permanecem em var/, especialmente var/coverage/, var/test-logs/ e var/quality/.

Documentação

• 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

Regras de design

• Mantenha as definições upstream na configuração central.
• Mantenha o estado de tempo de execução em $HOME/mcp/mcp-broker.
• Mantenha o inventário upstream privado em config/broker.private.yaml, que é ignorado pelo git.
• Mantenha valores secretos fora da configuração e do código-fonte.
• Não codifique caminhos pessoais no código-fonte, testes, documentação ou configuração pública.
• Execute operações de build, teste, tempo de execução e configuração por meio do Makefile.