mcp-multiplexer

mcp-multiplexer

Um servidor MCP que atende muitos. Aponte seu cliente de IA para o multiplexador e ele apresenta 7 meta-ferramentas em vez dos esquemas completos de ferramentas de cada servidor upstream — reduzindo drasticamente os tokens gastos para carregar definições de ferramentas no contexto do modelo no início da sessão.

O que ele faz

Cada servidor MCP que você configura envia todos os seus esquemas de ferramentas para o contexto do modelo antecipadamente. Com uma dúzia de servidores, isso são dezenas de milhares de tokens que o modelo quase nunca usa. O mcp-multiplexer é um servidor MCP (baseado em comando stdio e upstreams HTTP remotos) que expõe apenas:

Meta-ferramenta	O que retorna
list_servers	Visão geral: nome, status, contagem de ferramentas, instruções
list_tools(server)	Nomes das ferramentas, descrições de uma linha, anotações — sem esquemas
search_tools(query, server?, limit=5)	Ferramentas correspondentes com esquemas de entrada completos
describe_tool(server, tool)	Esquema de entrada completo de uma ferramenta exata
call_tool(server, tool, arguments)	Chamada proxy; resultados retornados na íntegra
refresh_tools(server?)	Reconectar e reconstruir o índice de ferramentas
authorize_server(server, pasted_url?)	Iniciar/concluir login OAuth para um servidor

O modelo descobre ferramentas de forma preguiçosa — lista e pesquisa primeiro, busca um esquema completo somente quando está prestes a chamar. O índice de ferramentas é armazenado em cache em ~/.cache/mcp-multiplexer/index.json para inicialização instantânea, e os servidores upstream conectam de forma preguiçosa.

Instalação

Binário pré-compilado (Linux x86_64/ARM64, macOS Intel/ARM, Windows x86_64 — sem necessidade de Rust): baixe o arquivo para sua plataforma em Releases e coloque mcp-multiplexer no seu 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/

A partir do código-fonte:

cargo install mcp-multiplexer

Qualquer uma das opções também instala mcp-mock, um pequeno servidor de eco usado pela suíte de testes — inofensivo, ignore-o.

Configuração

Formato padrão mcpServers (compatível com Claude Code / Claude Desktop), além de extras por servidor:

• expose: booleano — as ferramentas deste servidor também aparecem diretamente como server__tool, ignorando as meta-ferramentas. Veja Modo híbrido: expose.
• allow: lista de nomes exatos ou globs prefix* — apenas essas ferramentas ficam visíveis.
• deny: lista, sempre vence sobre allow.
• connect_timeout: segundos — tempo limite de conexão/inicialização (padrão 10). Aumente para servidores locais lentos para iniciar, ex.: uvx --from git+… que compila em toda inicialização a frio.

Strings em command, args, env, url e headers suportam expansão de ambiente ${VAR} (igual ao Claude Code). Uma variável não definida ou um ${ não fechado falha na inicialização com um erro claro — então mantenha segredos fora da configuração:

{
  "$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
    }
  }
}

Execute com mcp-multiplexer --config /path/to/.mcp.json (padrão para ./.mcp.json).

Modo híbrido: expose

A multiplexação troca um salto de descoberta (list_tools → describe_tool → call_tool) por um contexto de inicialização quase vazio. Para servidores que você chama toda sessão, muitas vezes, esse salto é pura sobrecarga — você já conhece a ferramenta, e o esquema dela custa alguns tokens. Defina "expose": true e as ferramentas desse servidor são montadas diretamente como ferramentas server__tool de primeira classe, com esquema e tudo, ao lado das meta-ferramentas:

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

O modelo então chama serena__find_symbol como qualquer ferramenta conectada diretamente — sem pesquisa, sem descrição, sem salto de proxy. O servidor permanece acessível através das meta-ferramentas também, e allow/deny ainda se aplicam. Regra prática: multiplexe a frota, exponha os favoritos.

OAuth

Servidores remotos que falam OAuth 2.1 (a especificação de autorização MCP) funcionam com "oauth": true em um servidor url — sem outra configuração no caso comum:

• O primeiro uso falha com uma URL de autorização. Abra-a, aprove; um ouvinte temporário 127.0.0.1 completa a troca. Repita a chamada e ela funciona. O modelo também pode conduzir isso por conta própria via a meta-ferramenta authorize_server.
• Os tokens ficam em ~/.cache/mcp-multiplexer/tokens.json (modo 0600), são atualizados automaticamente e sobrevivem a reinicializações — autorize uma vez por servidor.

Escopos são descobertos automaticamente; registro dinâmico de cliente é usado quando o provedor suporta — e se auto-corrige quando um provedor esquece o registro. Provedores que delegam autenticação a um domínio diferente do endpoint MCP (emissores entre domínios) funcionam imediatamente. Guia completo — fluxo de colar em modo headless, ajuste de oauth_client_id / oauth_scopes / oauth_redirect_port, notas do provedor (a pegadinha do alternância de grupo do GitLab), solução de problemas: docs/oauth.md.

Claude Code

Substitua todas as suas entradas mcpServers por uma apontando para o multiplexador:

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

Plugin (faz isso por você): este repositório é um plugin do Claude Code cuja habilidade setup instala o binário, migra seus servidores existentes para uma configuração de multiplexador (segredos viram referências ${VAR}, servidores OAuth são sinalizados), reconecta sua configuração do cliente e verifica:

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

Então peça ao Claude para "configurar mcp-multiplexer" (ou execute /mcp-multiplexer:setup).

Quando as ferramentas upstream mudam

O índice é construído na primeira conexão e armazenado em cache no disco. Se um servidor upstream adiciona ou remove ferramentas, chame refresh_tools (opcionalmente com um nome de servidor) para reindexar — sem necessidade de reiniciar. call_tool também se auto-corrige: uma chamada com falha aciona uma reconexão, reindexação e nova tentativa antes de exibir o erro.

Docker

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

O modo Docker é apenas para upstreams HTTP/remotos — upstreams stdio precisam de seus runtimes (node, uv, …) dentro da imagem.

Registro de logs

• --log-file <path> anexa logs a um arquivo; caso contrário, os logs vão para stderr (stdout é somente protocolo — não canalize ou redirecione).
• A variável de ambiente RUST_LOG controla o nível (ex.: RUST_LOG=debug); --verbose é uma abreviação para registro de depuração.

Estatísticas

mcp-multiplexer --stats imprime o que o mux está economizando para você (sem iniciar o servidor; lê ~/.cache/mcp-multiplexer/):

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

(exemplo: um servidor GitLab) além de bytes de esquema sob demanda servidos, contagens de chamadas proxy e uso por meta-ferramenta. Tokens são estimados como bytes/4 — uma heurística, não um tokenizador real. Com o plugin do Claude Code instalado, /mcp-multiplexer:gain mostra o mesmo relatório no chat.

Não-objetivos

• Recursos e prompts MCP (apenas ferramentas).
• Amostragem, elicitação e raízes upstream.
• Sem truncamento de resultados de ferramentas — retornados na íntegra.
• OAuth apenas para servidores url (servidores stdio usam env para segredos).
• Sem encaminhamento de notificações tools/list_changed — use refresh_tools.

Desenvolvimento

Contribuições são bem-vindas — veja CONTRIBUTING.md para configuração e a lista de verificação de CI, e SECURITY.md para relatar vulnerabilidades.

src/bin/mcp-mock.rs compila um binário de desenvolvimento mcp-mock (ferramentas echo/add/fail) usado pelos testes de integração.

cargo test

Depure interativamente com o MCP Inspector — observe o --, que mantém o próprio sinalizador --config do inspector de consumir o nosso:

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

Lançamentos

CHANGELOG.md documenta cada lançamento. Para cortar um:

1. Adicione uma seção ## [X.Y.Z] ao CHANGELOG.md e aumente version no Cargo.toml.
2. Faça commit como chore: release vX.Y.Z, crie a tag vX.Y.Z, envie commit e tag.

O fluxo de trabalho de tags verifica se a tag corresponde à versão do crate, cria o lançamento no GitHub com a seção do changelog como notas, anexa binários por plataforma com somas de verificação SHA256, publica no crates.io e envia imagens ghcr.io/johgirard/mcp-multiplexer marcadas como latest e vX.Y.Z.

Licença

MIT. Livre para qualquer uso, incluindo comercial — o único requisito é manter o aviso de direitos autorais.