MCP Proxy Hub

Agrega múltiplos servidores de recursos MCP em uma única interface usando um arquivo de configuração JSON.

GitHub
7
Experimente este MCPPatrocinado

Documentação

MCP Proxy Hub

Um servidor proxy MCP que agrega e serve múltiplos servidores de recursos MCP através de uma interface única. Este servidor atua como um hub central que pode:

  • Conectar-se e gerenciar múltiplos servidores de recursos MCP
  • Expor suas capacidades combinadas através de uma interface unificada
  • Lidar com o roteamento de solicitações para os servidores backend apropriados
  • Agregar respostas de múltiplas fontes

Recursos

Gerenciamento de Recursos

  • Descobrir e conectar-se a múltiplos servidores de recursos MCP
  • Agregar recursos de todos os servidores conectados
  • Manter esquemas de URI consistentes entre servidores
  • Lidar com roteamento e resolução de recursos

Agregação de Ferramentas

  • Expor ferramentas de todos os servidores conectados com prefixos de nome de servidor
  • Aplicar filtragem de ferramentas com base na configuração (exposedTools/hiddenTools)
  • Suportar renomeação de ferramentas via configuração
  • Roteamento de chamadas de ferramentas para os servidores backend apropriados

Suporte a Ferramentas Personalizadas

  • Definir ferramentas compostas que combinam funcionalidades de múltiplos servidores

  • Executar subferramentas usando especificações de nome de servidor e ferramenta

  • Fornecer documentação detalhada através de descrições de ferramentas

  • Especificar execução com um formato padronizado:

    {
  "server": "server_name",
  "tool": "tool_name",
  "args": {
    // Tool-specific arguments
  }
}

Suporte a Variáveis de Ambiente

  • Expandir automaticamente variáveis de ambiente em argumentos de ferramentas
  • Substituir automaticamente valores sensíveis por referências de variáveis nas respostas
  • Configurar quais variáveis devem ser expandidas/não expandidas via configuração
  • Suporte para variáveis de ambiente globais (todos os servidores) e específicas do servidor
  • Variáveis específicas do servidor têm precedência sobre variáveis globais com o mesmo nome
  • Cada variável pode ser configurada independentemente para expansão e não expansão
  • Variáveis de ambiente são expandidas apenas quando se usa a sintaxe ${VARIABLE_NAME} (ex.: ${API_KEY}). A sintaxe $VARIABLE_NAME não é suportada.
  • Tratamento seguro de informações sensíveis como chaves de API

Tratamento de Prompts

  • Agregar prompts de todos os servidores conectados
  • Roteamento de solicitações de prompts para os backends apropriados
  • Lidar com respostas de prompts de múltiplos servidores

Configuração

O servidor requer um arquivo de configuração JSON que especifica os servidores MCP aos quais se conectar. Copie o exemplo de configuração (config.example.json) e modifique-o conforme suas necessidades:

cp config.example.json config.json

Opções de Configuração

Configuração do Servidor MCP

  • Servidor tipo Stdio:

    • command: Comando a executar (obrigatório)
    • args: Argumentos de linha de comando (opcional)
    • env: Variáveis de ambiente (opcional)
    • exposedTools: Matriz de ferramentas a expor (opcional)
    • hiddenTools: Matriz de ferramentas a ocultar (opcional)
    • envVars: Configuração de variáveis de ambiente para argumentos e respostas de ferramentas (opcional)
    • timeout: Tempo limite de solicitação em segundos para chamadas de ferramentas downstream (opcional, substitui o timeout de nível superior; 0 desativa o tempo limite)
    • enable: Se deve habilitar o servidor (opcional, padrão: true)

  • Servidor tipo SSE:

    • type: "sse" (obrigatório)
    • url: URL do servidor SSE (obrigatório)
    • headers: Objeto de cabeçalhos HTTP a enviar com a conexão SSE (opcional)
    • exposedTools: Matriz de ferramentas a expor (opcional)
    • hiddenTools: Matriz de ferramentas a ocultar (opcional)
    • envVars: Configuração de variáveis de ambiente para argumentos e respostas de ferramentas (opcional)
    • timeout: Tempo limite de solicitação em segundos para chamadas de ferramentas downstream (opcional, substitui o timeout de nível superior; 0 desativa o tempo limite)
    • enable: Se deve habilitar o servidor (opcional, padrão: true)

  • Servidor tipo HTTP Transmissível (Streamable HTTP):

    • type: "streamable-http" (obrigatório)
    • url: URL do servidor HTTP Transmissível (obrigatório)
    • headers: Objeto de cabeçalhos HTTP a enviar com as solicitações (opcional)
    • exposedTools: Matriz de ferramentas a expor (opcional)
    • hiddenTools: Matriz de ferramentas a ocultar (opcional)
    • envVars: Configuração de variáveis de ambiente para argumentos e respostas de ferramentas (opcional)
    • timeout: Tempo limite de solicitação em segundos para chamadas de ferramentas downstream (opcional, substitui o timeout de nível superior; 0 desativa o tempo limite)
    • enable: Se deve habilitar o servidor (opcional, padrão: true)

Configuração de Filtragem de Ferramentas

  • exposedTools:

    • Expõe apenas as ferramentas especificadas
    • Matriz contendo strings (nomes originais de ferramentas) ou objetos {original, exposed} (para renomeação)

  • hiddenTools:

    • Oculta as ferramentas especificadas
    • Matriz de strings de nomes de ferramentas a ocultar

Configuração de Variáveis de Ambiente

  • envVars específicos do servidor:

    • Matriz de configurações de variáveis de ambiente para um servidor específico

    • Cada configuração tem as seguintes propriedades:

      • name: Nome da variável de ambiente
      • value: Valor da variável de ambiente
      • expand: Se deve expandir esta variável em argumentos de ferramentas (opcional, padrão: false)
      • unexpand: Se deve não expandir esta variável em respostas de ferramentas (opcional, padrão: false)

    • Exemplo:

      "envVars": [
  { "name": "API_KEY", "value": "my-api-key", "expand": true, "unexpand": true },
  { "name": "USER_ID", "value": "user123", "expand": true, "unexpand": false }
]

  • envVars globais:

    • Matriz de configurações de variáveis de ambiente aplicadas a todos os servidores

    • Usa o mesmo formato de configuração que envVars específicos do servidor

    • Variáveis específicas do servidor com o mesmo nome substituem variáveis globais

    • Definidas no nível raiz do arquivo de configuração

    • Exemplo:

      "envVars": [
  { "name": "GLOBAL_API_KEY", "value": "global-api-key", "expand": true, "unexpand": true },
  { "name": "GLOBAL_ENV", "value": "production", "expand": true, "unexpand": false }
]

Configuração de Tempo Limite

Controla quanto tempo o hub proxy aguarda um servidor downstream responder a uma chamada de ferramenta (tools/call) ou listagem de ferramentas (tools/list) antes de abortar.

  • timeout de nível superior: Padrão global em segundos aplicado a todos os servidores.
  • timeout por servidor (dentro de cada mcpServers[name]): Substitui o valor global para aquele servidor.
  • 0: Desativa o tempo limite para aquele escopo (sem limite superior).
  • Não definido: Usa o padrão do SDK MCP (60 segundos).

Valores cuja conversão em milissegundos (timeout * 1000) exceda 2147483647 ms (o atraso máximo seguro de setTimeout) são limitados a esse teto. Valores negativos, NaN ou não numéricos são ignorados e passam para o próximo nível com um aviso.

Exemplo:

{
  "timeout": 30,
  "mcpServers": {
    "slow-server": { "command": "...", "timeout": 0 },
    "fast-server": { "command": "...", "timeout": 5 }
  }
}

Configuração de Transporte do Servidor

Configure como o próprio hub proxy é servido através da seção serverTransport:

"serverTransport": {
  "type": "streamable-http",
  "port": 3006,
  "host": "0.0.0.0",
  "path": "/mcp",
  "auth": {
    "type": "bearer",
    "token": "your-secret-token"
  }
}
  • type: Tipo de transporte ("stdio", "sse" ou "streamable-http")
  • port: Número da porta para transportes baseados em HTTP (padrão: 3006)
  • host: Host ao qual vincular (padrão: "0.0.0.0")
  • path: Caminho da URL para o endpoint HTTP Transmissível (padrão: "/mcp")
  • auth: Configuração de autenticação (opcional)
    • type: "bearer" (atualmente o único tipo suportado)
    • token: O token bearer necessário para autenticação

A autenticação também pode ser configurada através da variável de ambiente MCP_PROXY_AUTH_TOKEN.

Configuração de Ferramentas Personalizadas

  • tools:
    • Objeto com nomes de ferramentas personalizadas como chaves
    • Cada ferramenta tem description e subtools
    • subtools é chaveado por nome de servidor e contém a lista de ferramentas de cada servidor

Variáveis de Ambiente

  • MCP_PROXY_CONFIG_PATH: Caminho para o arquivo de configuração
  • MCP_PROXY_LOG_DIRECTORY_PATH: Caminho para o diretório de logs
  • MCP_PROXY_LOG_LEVEL: Nível de log ("debug" ou "info")
  • MCP_PROXY_AUTH_TOKEN: Token bearer para autenticar solicitações recebidas no servidor proxy
  • MCP_PROXY_PATH: Caminho da URL para o endpoint HTTP Transmissível (padrão: "/mcp")
  • KEEP_SERVER_OPEN: Se deve manter o servidor aberto após desconexão do cliente no modo SSE (defina como "1" para habilitar)
  • PORT: Porta para o servidor SSE/HTTP Transmissível (padrão: 3006)
  • HOST: Host ao qual vincular para o servidor HTTP (padrão: "0.0.0.0")

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Para desenvolvimento com execução contínua:

# Stdio
npm run dev
# SSE
npm run dev:sse
# Streamable HTTP
npm run dev:http

CLI

A CLI fornece dois modos de operação para interagir com o MCP Proxy Hub.

Modo de Execução Direta

Você pode executar comandos diretamente do seu terminal. Isso é útil para scripts e automação.

  • Listar ferramentas disponíveis:

    mcp-proxy-hub-cli list

  • Chamar uma ferramenta:

    mcp-proxy-hub-cli call <toolName> [args...]
    • toolName: O nome da ferramenta a chamar.
    • args: Argumentos para a ferramenta no formato key=value.
    • --output-dir <dir> ou -o <dir>: Salvar a saída em um diretório.

    Exemplo:

    mcp-proxy-hub-cli call my_tool param1=value1 -o output

Modo Interativo

Se você executar a CLI sem argumentos, ela iniciará no modo interativo. Isso fornece uma interface semelhante a um shell para executar comandos.

mcp-proxy-hub-cli

Uma vez no modo interativo, você pode usar os seguintes comandos:

  • list: Listar ferramentas disponíveis.
  • call <toolName> [args...]: Chamar uma ferramenta com argumentos.
  • exit: Sair da sessão interativa.

Instalação

Para usar com o Claude Desktop, adicione a configuração do servidor:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-proxy-hub": {
      "command": "/path/to/mcp-proxy-hub/build/index.js",
      "env": {
        "MCP_PROXY_CONFIG_PATH": "/absolute/path/to/your/config.json",
        "KEEP_SERVER_OPEN": "1"
      }
    }
  }
}

KEEP_SERVER_OPEN manterá o SSE em execução mesmo se um cliente desconectar. Isso é útil quando múltiplos clientes se conectam ao proxy MCP.

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como um script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar ferramentas de depuração no seu navegador.