MCP Proxy Server

Agrega múltiplos servidores de recursos MCP em uma única interface com suporte a stdio/sse.

GitHub

193

Experimente este MCPPatrocinado

Documentação

MCP Proxy Server

简体中文

✨ Destaques dos Principais Recursos

🌐 Gerenciamento via Web UI: Gerencie facilmente todos os servidores MCP conectados através de uma interface web intuitiva (opcional, requer ativação).
🔧 Controle Granular de Ferramentas: Ative ou desative ferramentas individuais e substitua nomes/descrições via Web UI.
🛡️ Autenticação Flexível de Endpoints: Proteja seus endpoints baseados em HTTP (/sse, /mcp) com opções de autenticação flexíveis (Authorization: Bearer <token> ou X-API-Key: <key>).
🔄 Gerenciamento Robusto de Sessões e Concorrência:
- Gerenciamento aprimorado de sessões SSE para reconexões de clientes (dependendo de eventos endpoint enviados pelo servidor) e suporte a conexões concorrentes.
- O endpoint HTTP Streamable (/mcp) também suporta interações concorrentes de clientes.
🚀 Operações MCP Versáteis (Servidor e Proxy):
- Atua como Proxy: Conecta-se e agrega múltiplos servidores MCP de backend de vários tipos (Stdio, SSE, Streamable HTTP).
- Atua como Servidor: Expõe essas capacidades agregadas através de seus próprios endpoints Streamable HTTP (/mcp) e SSE (/sse). Também pode rodar em modo puramente Stdio.
✨ Saída de Instalação em Tempo Real: Monitore o progresso da instalação de servidores Stdio (stdout/stderr) diretamente na Web UI.
✨ Terminal Web: Acesse um terminal de linha de comando dentro da Admin UI para interação direta com o servidor (opcional, use com cautela devido aos riscos de segurança).

Este servidor atua como um hub central para servidores de recursos do Model Context Protocol (MCP). Ele pode:

Conectar-se e gerenciar múltiplos servidores MCP de backend (tipos Stdio, SSE e Streamable HTTP).
Expor suas capacidades combinadas (ferramentas, recursos) através de uma interface SSE unificada, uma interface Streamable HTTP, ou atuar como um único servidor MCP baseado em Stdio.
Lidar com o roteamento de requisições para os servidores de backend apropriados.
Agregar respostas se necessário (embora atue principalmente como um proxy).
Suportar múltiplas conexões SSE simultâneas de clientes com autenticação opcional por chave de API.

Recursos

Gerenciamento de Recursos e Ferramentas via Proxy

Descobre e conecta-se a múltiplos servidores de recursos MCP definidos em config/mcp_server.json.
Agrega ferramentas e recursos de todos os servidores ativos conectados.
Roteia chamadas de ferramentas e requisições de acesso a recursos para o servidor de backend correto.
Mantém esquemas de URI consistentes.

✨ Admin UI Web Opcional (`ENABLE_ADMIN_UI=true`)

Fornece uma interface baseada em navegador para gerenciar a configuração do servidor proxy e as ferramentas conectadas. Os recursos incluem:

Configuração de Servidores: Visualize, adicione, edite e exclua entradas de servidores (mcp_server.json). Suporta tipos de servidores Stdio, SSE e HTTP com opções relevantes (tipo, comando, argumentos, env, url, apiKey, bearerToken, configuração de instalação).
Configuração de Ferramentas: Visualize todas as ferramentas descobertas dos servidores de backend ativos. Ative ou desative ferramentas específicas. Substitua o nome de exibição e a descrição de cada ferramenta (tool_config.json).
Recarga ao Vivo: Aplique alterações na configuração de servidores e ferramentas acionando uma recarga de configuração sem precisar reiniciar todo o processo do servidor proxy.
Instalação de Servidores Stdio: Para servidores Stdio, você pode definir comandos de instalação na configuração. A Admin UI permite que você:
- Acione a execução desses comandos de instalação.
- Monitore o progresso da instalação em tempo real com saída ao vivo de stdout e stderr transmitida diretamente para a UI.
Terminal Web: Acesse um terminal web integrado que fornece acesso ao shell do ambiente onde o servidor proxy está rodando.
- Aviso de Segurança: Este recurso concede acesso significativo e deve ser usado com extrema cautela, especialmente se a interface administrativa estiver exposta.

Configuração

A configuração é feita principalmente através de variáveis de ambiente e arquivos JSON localizados no diretório ./config.

1. Conexões de Servidores (`config/mcp_server.json`)

Este arquivo define os servidores MCP de backend aos quais o proxy deve se conectar.

Exemplo de config/mcp_server.json:

{
  "mcpServers": {
    "unique-server-key1": {
      "type": "stdio",
      "name": "My Stdio Server",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "type": "sse",
      "name": "My SSE Server",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "http-mcp-server": {
      "type": "http",
      "name": "My Streamable HTTP Server",
      "active": true,
      "url": "http://localhost:8081/mcp",
      "bearerToken": "some_secure_token_for_http_server"
    },
    "stdio-default-install": {
        "type": "stdio",
        "name": "Stdio Server with Default Install Path",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo 'Installing to default location...'"]
    }
  }
}

Campos:

mcpServers: (Obrigatório) Um objeto onde cada chave é um identificador único para um servidor de backend.
name: (Opcional) Um nome de exibição amigável para o servidor (usado na Admin UI).
active: (Opcional, padrão: true) Defina como false para impedir que o proxy se conecte a este servidor.
type: (Obrigatório) Especifica o tipo de transporte. Deve ser um de "stdio", "sse" ou "http".
command: (Obrigatório se type for "stdio") O comando para executar o processo do servidor.
args: (Opcional se type for "stdio") Um array de argumentos de string para passar ao comando.
env: (Opcional se type for "stdio") Um objeto de variáveis de ambiente (KEY: "value") para definir no processo do servidor. Elas são mescladas com o ambiente do servidor proxy.
url: (Obrigatório se type for "sse" ou "http") A URL completa do endpoint do servidor de backend (ex.: endpoint SSE para "sse", endpoint MCP para "http").
apiKey: (Opcional se type for "sse" ou "http") Uma chave de API para enviar no cabeçalho X-Api-Key quando o proxy se conecta a este backend específico.
bearerToken: (Opcional se type for "sse" ou "http") Um token para enviar no cabeçalho Authorization: Bearer <token> ao conectar-se a este backend específico. (Se ambos apiKey e bearerToken forem fornecidos, bearerToken geralmente tem precedência para essa conexão de backend específica).
installDirectory: (Opcional se type for "stdio") O caminho absoluto onde o servidor em si deve ser instalado (ex.: /opt/my-server-files). Usado pelo recurso de instalação da Admin UI.
- Se fornecido em mcp_server.json, este caminho exato é usado.
- Se omitido, o diretório efetivo depende da variável de ambiente TOOLS_FOLDER (veja a seção Variáveis de Ambiente).
  - Se TOOLS_FOLDER estiver definido e não vazio, o servidor será instalado em um subdiretório nomeado após a chave do servidor dentro desta pasta (ex.: ${TOOLS_FOLDER}/<server_key>).
  - Se TOOLS_FOLDER também estiver vazio ou não definido, o padrão será um subdiretório tools dentro do diretório de trabalho do servidor proxy (ex.: ./tools/<server_key>).
- Certifique-se de que o diretório pai do caminho de instalação alvo (ex.: TOOLS_FOLDER ou ./tools) seja gravável pelo usuário que executa o servidor proxy.
installCommands: (Opcional para tipo Stdio) Um array de comandos de shell executados sequencialmente pelo recurso de instalação da Admin UI se o diretório do servidor alvo (derivado de installDirectory ou padrões) não existir. Os comandos são executados a partir do diretório pai do diretório de instalação do servidor alvo (ex.: se installDirectory resolver para /opt/tools/my-server, os comandos rodam em /opt/tools/). Use com extrema cautela devido aos riscos de segurança.

2. Configuração de Ferramentas (`config/tool_config.json`)

Este arquivo permite substituir propriedades de ferramentas descobertas dos servidores de backend. É gerenciado principalmente via Admin UI, mas pode ser editado manualmente.

Exemplo de config/tool_config.json:

{
  "tools": {
    "unique-server-key1__tool-name-from-server": {
      "enabled": true,
      "displayName": "My Custom Tool Name",
      "description": "A more user-friendly description."
    },
    "another-sse-server__another-tool": {
      "enabled": false
    }
  }
}

As chaves estão no formato <server_key><separator><original_tool_name>, onde <separator> é o valor da variável de ambiente SERVER_TOOLNAME_SEPERATOR (padrão: __).
enabled: (Opcional, padrão: true) Defina como false para ocultar esta ferramenta dos clientes que se conectam ao proxy.
displayName: (Opcional) Substitui o nome da ferramenta nas UIs dos clientes.
description: (Opcional) Substitui a descrição da ferramenta.

3. Variáveis de Ambiente

PORT: Porta para os endpoints baseados em HTTP do servidor proxy (/sse, /mcp e Admin UI, se habilitada). Padrão: 3663. Nota: Isso é usado apenas quando rodando em um modo que inicia um servidor HTTP (ex.: via npm run dev:sse ou o contêiner Docker). O script npm run dev roda em modo Stdio.
```
export PORT=8080
```
ALLOWED_KEYS: (Opcional) Lista separada por vírgulas de chaves de API para proteger os endpoints baseados em HTTP do proxy (/sse, /mcp). Se nem ALLOWED_KEYS nem ALLOWED_TOKENS estiverem definidos, a autenticação é desabilitada para esses endpoints. Os clientes devem fornecer uma chave via cabeçalho X-Api-Key ou parâmetro de consulta ?key=.
```
export ALLOWED_KEYS="client_key1,client_key2"
```
ALLOWED_TOKENS: (Opcional) Lista separada por vírgulas de Bearer Tokens para proteger os endpoints baseados em HTTP do proxy (/sse, /mcp). Se nem ALLOWED_KEYS nem ALLOWED_TOKENS estiverem definidos, a autenticação é desabilitada. Os clientes devem fornecer um token via cabeçalho Authorization: Bearer <token>. Se ambos ALLOWED_KEYS e ALLOWED_TOKENS estiverem configurados, a autenticação Bearer Token será tentada primeiro.
```
export MCP_PROXY_SSE_ALLOWED_TOKENS="your_bearer_token_1,your_bearer_token_2"
```
ENABLE_ADMIN_UI: (Opcional) Defina como true para habilitar a Admin UI Web (aplicável apenas no modo SSE). Padrão: false.
```
export ENABLE_ADMIN_UI=true
```
ADMIN_USERNAME: (Obrigatório se a Admin UI estiver habilitada) Nome de usuário para login na Admin UI. Padrão: admin.
ADMIN_PASSWORD: (Obrigatório se a Admin UI estiver habilitada) Senha para login na Admin UI. Padrão: password (Altere isso!).
```
export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!
```
SESSION_SECRET: (Opcional, recomendado se a Admin UI estiver habilitada) Segredo usado para assinar cookies de sessão. Se não definido, um segredo padrão menos seguro é usado e um aviso é emitido. Um segredo seguro é gerado automaticamente e salvo em config/.session_secret na primeira execução se não for fornecido via variável de ambiente.
```
# Recommended: Generate a strong secret (e.g., openssl rand -hex 32)
export SESSION_SECRET='your_very_strong_random_secret_here'
```
TOOLS_FOLDER: (Opcional) Especifica o diretório base para instalações de servidores Stdio iniciadas via Admin UI, usado quando installDirectory não está explicitamente definido em mcp_server.json para um servidor específico.
- Se definido (ex.: /custom/tools_path), instalações para servidores sem um installDirectory específico terão como alvo um subdiretório nomeado após a chave do servidor dentro desta pasta (ex.: ${TOOLS_FOLDER}/<server_key>).
- Se TOOLS_FOLDER não estiver definido ou estiver vazio, tais instalações usarão por padrão um subdiretório tools dentro do diretório de trabalho do servidor proxy (ex.: ./tools/<server_key>).
- O Dockerfile define isso como /tools por padrão.
```
export TOOLS_FOLDER=/srv/mcp_tools
```
SERVER_TOOLNAME_SEPERATOR: (Opcional) Define o separador usado para combinar o nome do servidor e o nome da ferramenta ao gerar a chave única para ferramentas (ex.: server-key__tool-name). Esta chave é usada internamente e no arquivo tool_config.json.
- Padrão: __.
- Deve ter pelo menos 2 caracteres e conter apenas letras (a-z, A-Z), números (0-9), hífens (-) e sublinhados (_).
- Se o valor fornecido for inválido, o padrão (__) será usado e um aviso será registrado.
```
export SERVER_TOOLNAME_SEPERATOR="___" # Example: using triple underscore
```
LOGGING: (Opcional) Controla o nível mínimo de log emitido pelo servidor.
- Valores possíveis (insensíveis a maiúsculas/minúsculas): error, warn, info, debug.
- Logs no nível especificado e todos os níveis acima dele serão exibidos.
- Padrão: info.
```
export LOGGING="debug"
```
RETRY_SSE_TOOL_CALL: (Opcional) Controla se as tentativas de repetição para chamadas de ferramentas SSE são habilitadas. Defina como "true" para habilitar, "false" para desabilitar. Padrão: true. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export RETRY_SSE_TOOL_CALL="true"
```
SSE_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de tentativas de repetição para chamadas de ferramentas SSE (após a falha inicial). Padrão: 2. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export SSE_TOOL_CALL_MAX_RETRIES="2"
```
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Atraso base em milissegundos para tentativas de repetição de chamadas de ferramentas SSE, usado em backoff exponencial. Padrão: 300. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="300"
```
RETRY_HTTP_TOOL_CALL: (Opcional) Controla se deve repetir em erros de conexão de chamadas de ferramentas HTTP. Defina como "true" para habilitar, "false" para desabilitar. Padrão: true. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export RETRY_HTTP_TOOL_CALL="true"
```
HTTP_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de tentativas de repetição para chamadas de ferramentas HTTP (após a falha inicial). Padrão: 2. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export HTTP_TOOL_CALL_MAX_RETRIES="3"
```
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Atraso base em milissegundos para tentativas de repetição de chamadas de ferramentas HTTP, usado em backoff exponencial. Padrão: 300. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"
```
RETRY_STDIO_TOOL_CALL: (Opcional) Controla se deve repetir em erros de conexão de chamadas de ferramentas Stdio (tenta reiniciar o processo). Defina como "true" para habilitar, "false" para desabilitar. Padrão: true. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export RETRY_STDIO_TOOL_CALL="true"
```
STDIO_TOOL_CALL_MAX_RETRIES: (Opcional) Número máximo de tentativas de repetição para chamadas de ferramentas Stdio (após a falha inicial). Padrão: 2. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export STDIO_TOOL_CALL_MAX_RETRIES="5"
```
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS: (Opcional) Atraso base em milissegundos para tentativas de repetição de chamadas de ferramentas Stdio, usado em backoff exponencial. Padrão: 300. Consulte a seção "Recursos de Confiabilidade Aprimorada" para detalhes.
```
export STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS="1000"
```

Recursos de Confiabilidade Aprimorada

O MCP Proxy Server inclui recursos para melhorar sua resiliência e a confiabilidade das interações com serviços MCP de backend, garantindo operações mais suaves e execução de ferramentas mais consistente.

1. Propagação de Erros

O servidor proxy garante que erros originados dos serviços MCP de backend sejam consistentemente propagados ao cliente solicitante. Esses erros são formatados como respostas de erro JSON-RPC padrão, facilitando o tratamento uniforme pelos clientes.

2. Tentativa de Repetição de Chamadas de Ferramentas SSE

Quando uma operação tools/call é feita a um servidor backend baseado em SSE, e a conexão subjacente é perdida ou sofre um erro (incluindo timeouts), o servidor proxy implementa um mecanismo de repetição.

Mecanismo de Repetição: Se uma chamada de ferramenta SSE inicial falhar devido a um erro de conexão ou timeout, o proxy tentará restabelecer a conexão com o backend SSE. Se a reconexão for bem-sucedida, ele repetirá a solicitação tools/call original usando uma estratégia de backoff exponencial, semelhante às repetições HTTP e Stdio. Isso significa que o atraso antes de cada tentativa de repetição subsequente aumenta exponencialmente, com uma pequena quantidade de jitter (aleatoriedade) adicionada.

Configuração: Essas configurações são controladas principalmente por variáveis de ambiente. Valores em config/mcp_server.json sob o objeto proxy para essas chaves específicas serão substituídos por variáveis de ambiente, se definidas.

RETRY_SSE_TOOL_CALL (variável de ambiente):
- Defina como "true" para habilitar repetições para chamadas de ferramentas SSE.
- Defina como "false" para desabilitar este recurso.
- Comportamento Padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou tiver um valor inválido).
SSE_TOOL_CALL_MAX_RETRIES (variável de ambiente):
- Especifica o número máximo de tentativas de repetição após a tentativa inicial com falha. Por exemplo, se definido como "2", haverá uma tentativa inicial e até duas tentativas de repetição, totalizando no máximo três tentativas.
- Comportamento Padrão: 2 (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS (variável de ambiente):
- O atraso base em milissegundos usado no cálculo de backoff exponencial. O atraso antes da n-ésima tentativa de repetição (indexada a partir de 0) é aproximadamente SSE_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
- Comportamento Padrão: 300 (milissegundos) (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).

Exemplo (Variáveis de Ambiente):

export RETRY_SSE_TOOL_CALL="true"
export SSE_TOOL_CALL_MAX_RETRIES="3"
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

3. Repetição de Solicitações HTTP para Chamadas de Ferramentas

Para operações tools/call direcionadas a servidores backend baseados em HTTP, o proxy implementa um mecanismo de repetição para erros de conexão (por exemplo, "falha ao buscar", timeouts de rede).

Mecanismo de Repetição: Se uma solicitação HTTP inicial falhar devido a um erro de conexão, o proxy repetirá a solicitação usando uma estratégia de backoff exponencial. Isso significa que o atraso antes de cada tentativa de repetição subsequente aumenta exponencialmente, com uma pequena quantidade de jitter (aleatoriedade) adicionada para evitar cenários de "manada" (thundering herd).

Configuração: Essas configurações são controladas principalmente por variáveis de ambiente.

RETRY_HTTP_TOOL_CALL (variável de ambiente):
- Defina como "true" para habilitar repetições para chamadas de ferramentas HTTP.
- Defina como "false" para desabilitar este recurso.
- Comportamento Padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou tiver um valor inválido).
HTTP_TOOL_CALL_MAX_RETRIES (variável de ambiente):
- Especifica o número máximo de tentativas de repetição após a tentativa inicial com falha. Por exemplo, se definido como "2", haverá uma tentativa inicial e até duas tentativas de repetição, totalizando no máximo três tentativas.
- Comportamento Padrão: 2 (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (variável de ambiente):
- O atraso base em milissegundos usado no cálculo de backoff exponencial. O atraso antes da n-ésima tentativa de repetição (indexada a partir de 0) é aproximadamente HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
- Comportamento Padrão: 300 (milissegundos) (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).

4. Repetição de Conexão Stdio para Chamadas de Ferramentas

Para operações tools/call direcionadas a servidores backend baseados em Stdio, o proxy implementa um mecanismo de repetição para erros de conexão (por exemplo, falha do processo ou falta de resposta).

Mecanismo de Repetição: Se uma conexão Stdio inicial ou chamada de ferramenta falhar, o proxy tentará reiniciar o processo Stdio e repetir a solicitação. Este mecanismo segue uma estratégia de backoff exponencial semelhante às repetições HTTP.

Configuração: Essas configurações são controladas principalmente por variáveis de ambiente.

RETRY_STDIO_TOOL_CALL (variável de ambiente):
- Defina como "true" para habilitar repetições de chamadas de ferramentas Stdio.
- Defina como "false" para desabilitar este recurso.
- Comportamento Padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou tiver um valor inválido).
STDIO_TOOL_CALL_MAX_RETRIES (variável de ambiente):
- Especifica o número máximo de tentativas de repetição após a tentativa inicial com falha. Por exemplo, se definido como "2", haverá uma tentativa inicial e até duas tentativas de repetição, totalizando no máximo três tentativas.
- Comportamento Padrão: 2 (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (variável de ambiente):
- O atraso base em milissegundos usado no cálculo de backoff exponencial. O atraso antes da n-ésima tentativa de repetição (indexada a partir de 0) é aproximadamente STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
- Comportamento Padrão: 300 (milissegundos) (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).

Notas Gerais sobre a Interpretação de Variáveis de Ambiente:

Variáveis de ambiente booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) são consideradas true se seu valor em minúsculas for exatamente "true". Qualquer outro valor (incluindo vazio ou não definido) resulta na aplicação do padrão ou false se o padrão for false (embora para essas variáveis específicas, o padrão seja true).
Variáveis de ambiente numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) são interpretadas como inteiros de base 10. Se a interpretação falhar (por exemplo, o valor não é um número, ou a variável está vazia/não definida), o valor padrão é usado.

Desenvolvimento

1. Propagação de Erros

2. Repetição de Conexão SSE para Chamadas de Ferramentas

Quando uma operação tools/call é feita a um servidor backend baseado em SSE, e a conexão subjacente é perdida ou sofre um erro, o servidor proxy tentará automaticamente:

Restabelecer a conexão com o backend SSE.
Se a reconexão for bem-sucedida, ele repetirá a solicitação tools/call original uma vez.

Este comportamento ajuda a mitigar problemas de rede transitórios que possam interromper temporariamente as conexões SSE.

Configuração: Este recurso é controlado principalmente pela variável de ambiente RETRY_SSE_TOOL_CALL_ON_DISCONNECT.

RETRY_SSE_TOOL_CALL_ON_DISCONNECT (variável de ambiente):
- Defina como "true" para habilitar a reconexão e repetição automáticas.
- Defina como "false" para desabilitar este recurso.
- Comportamento Padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou tiver um valor inválido).
- Nota: Se esta configuração também estiver presente em config/mcp_server.json sob proxy, a variável de ambiente tem precedência.

Exemplo (Variável de Ambiente):

export RETRY_SSE_TOOL_CALL_ON_DISCONNECT="true"

(O exemplo JSON para mcp_server.json em "Configuração de Comportamento do Proxy" ilustra onde outras configurações do proxy podem ser colocadas, mas esta configuração específica é melhor gerenciada por meio de sua variável de ambiente.)

3. Repetição de Solicitações HTTP para Chamadas de Ferramentas

RETRY_HTTP_TOOL_CALL (variável de ambiente):
- Defina como "true" para habilitar repetições para chamadas de ferramentas HTTP.
- Defina como "false" para desabilitar este recurso.
- Comportamento Padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou tiver um valor inválido).
HTTP_TOOL_CALL_MAX_RETRIES (variável de ambiente):
- Especifica o número máximo de tentativas de repetição após a tentativa inicial falha. Por exemplo, se definido como "2", haverá uma tentativa inicial e até duas tentativas de repetição, totalizando no máximo três tentativas.
- Comportamento padrão: 2 (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS (variável de ambiente):
- O atraso base em milissegundos usado no cálculo de backoff exponencial. O atraso antes da n-ésima tentativa (indexada a partir de 0) é aproximadamente HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
- Comportamento padrão: 300 (milissegundos) (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).

Notas gerais sobre a análise de variáveis de ambiente:

Variáveis de ambiente booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) são consideradas true se o valor em minúsculas for exatamente "true". Qualquer outro valor (incluindo vazio ou não definido) resulta na aplicação do padrão ou em false se o padrão for false (embora, para essas variáveis específicas, o padrão seja true).
Variáveis de ambiente numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) são analisadas como inteiros de base 10. Se a análise falhar (por exemplo, o valor não é um número, ou a variável está vazia/não definida), o valor padrão é usado.

Exemplo (variáveis de ambiente):

export RETRY_HTTP_TOOL_CALL="true"
export HTTP_TOOL_CALL_MAX_RETRIES="3"
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"

4. Repetição de conexão Stdio para chamadas de ferramentas

Mecanismo de repetição: Se uma conexão Stdio inicial ou chamada de ferramenta falhar, o proxy tentará reiniciar o processo Stdio e repetir a solicitação. Esse mecanismo segue uma estratégia de backoff exponencial semelhante às repetições HTTP.

Configuração: Essas configurações são controladas principalmente por variáveis de ambiente.

RETRY_STDIO_TOOL_CALL (variável de ambiente):
- Defina como "true" para habilitar repetições de chamadas de ferramentas Stdio.
- Defina como "false" para desabilitar esse recurso.
- Comportamento padrão: true (se a variável de ambiente não estiver definida, estiver vazia ou for um valor inválido).
STDIO_TOOL_CALL_MAX_RETRIES (variável de ambiente):
- Especifica o número máximo de tentativas de repetição após a tentativa inicial falha. Por exemplo, se definido como "2", haverá uma tentativa inicial e até duas tentativas de repetição, totalizando no máximo três tentativas.
- Comportamento padrão: 2 (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS (variável de ambiente):
- O atraso base em milissegundos usado no cálculo de backoff exponencial. O atraso antes da n-ésima tentativa (indexada a partir de 0) é aproximadamente STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS * (2^n) + jitter.
- Comportamento padrão: 300 (milissegundos) (se a variável de ambiente não estiver definida, estiver vazia ou não for um inteiro válido).

Notas gerais sobre a análise de variáveis de ambiente:

Variáveis de ambiente booleanas (RETRY_SSE_TOOL_CALL, RETRY_HTTP_TOOL_CALL, RETRY_STDIO_TOOL_CALL) são consideradas true se o valor em minúsculas for exatamente "true". Qualquer outro valor (incluindo vazio ou não definido) resulta na aplicação do padrão ou em false se o padrão for false (embora, para essas variáveis específicas, o padrão seja true).
Variáveis de ambiente numéricas (SSE_TOOL_CALL_MAX_RETRIES, SSE_TOOL_CALL_RETRY_DELAY_BASE_MS, HTTP_TOOL_CALL_MAX_RETRIES, HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS, STDIO_TOOL_CALL_MAX_RETRIES, STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS) são analisadas como inteiros de base 10. Se a análise falhar (por exemplo, o valor não é um número, ou a variável está vazia/não definida), o valor padrão é usado.

Desenvolvimento

Instale as dependências:

npm install
# or yarn install

Compile o servidor (compila TypeScript para JavaScript em build/):

npm run build

Execute em modo de desenvolvimento (usa tsx para execução direta de TS com reinício automático em alterações):

# Run as a Stdio MCP server (default mode)
npm run dev

# Run as an SSE MCP server (enables SSE endpoint and Admin UI if configured)
# Ensure environment variables (PORT, ENABLE_ADMIN_UI etc.) are set as needed
ENABLE_ADMIN_UI=true npm run dev:sse

Monitore alterações e recompile automaticamente (útil se não estiver usando tsx):

npm run watch

Executando com Docker

Um Dockerfile é fornecido. O contêiner executa o servidor em modo SSE por padrão (usando build/sse.js) e inclui todas as dependências necessárias. A variável de ambiente TOOLS_FOLDER tem como padrão /tools dentro do contêiner.

Recomendado: Usando a imagem pré-construída (do GHCR)

É recomendado usar a imagem pré-construída do GitHub Container Registry para facilitar a configuração. Fornecemos dois tipos de imagens:

Imagem padrão (enxuta): Esta é a imagem padrão e recomendada para a maioria dos usuários. Ela contém a funcionalidade principal do MCP Proxy Server.

Tags: latest, <version> (por exemplo, 0.1.2)

# Pull the latest standard image
docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

# Or pull a specific version
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:0.1.2

Imagem agrupada (completa): Esta imagem inclui um conjunto de servidores MCP pré-instalados e dependências do navegador Playwright. É significativamente maior, mas fornece acesso imediato a ferramentas comuns.
- Tag: <version>-bundled-mcpservers-playwright (por exemplo, 0.1.2-bundled-mcpservers-playwright) ou latest-bundled-mcpservers-playwright
```
# Pull a bundled version
# docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest-bundled-mcpservers-playwright
```
A imagem agrupada inclui os seguintes componentes pré-instalados (via argumentos de build do Docker):
- Pacotes PIP (PRE_INSTALLED_PIP_PACKAGES_ARG):
  - mcp-server-time
  - markitdown-mcp
  - mcp-proxy
- Pacotes NPM (PRE_INSTALLED_NPM_PACKAGES_ARG):
  - g-search-mcp
  - fetcher-mcp
  - playwright
  - time-mcp
  - mcp-trends-hub
  - @adenot/mcp-google-search
  - edgeone-pages-mcp
  - @modelcontextprotocol/server-filesystem
  - mcp-server-weibo
  - @variflight-ai/variflight-mcp
  - @baidumap/mcp-server-baidu-map
  - @modelcontextprotocol/inspector
- Comando de inicialização (PRE_INSTALLED_INIT_COMMAND_ARG):
  - playwright install --with-deps chromium

Escolha o tipo de imagem que melhor atende às suas necessidades. Para a maioria dos usuários, a imagem padrão é suficiente, e os servidores MCP backend podem ser configurados via mcp_server.json.

Em seguida, execute a imagem do contêiner escolhida:

docker run -d \
  -p 3663:3663 \
  -e PORT=3663 \
  -e ENABLE_ADMIN_UI=true \
  -e ADMIN_USERNAME=myadmin \
  -e ADMIN_PASSWORD=yoursupersecretpassword \
  -e ALLOWED_KEYS="clientkey1" \
  -e TOOLS_FOLDER=/my/custom_tools_volume # Optional: Override default /tools for server installations
  -v ./my_config:/mcp-proxy-server/config \
  -v /path/on/host/to/tools:/my/custom_tools_volume `# Mount a volume for TOOLS_FOLDER if overridden` \
  --name mcp-proxy-server \
  ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest

Substitua ./my_config pelo caminho do host contendo mcp_server.json e opcionalmente tool_config.json. O contêiner espera arquivos de configuração em /app/config.
Se você substituir TOOLS_FOLDER para instalações de servidores via Admin UI, certifique-se de montar um volume correspondente (por exemplo, -v /path/on/host/for_tools:/my/custom_tools_volume). Se estiver usando o padrão /tools (definido por TOOLS_FOLDER no Dockerfile), você pode montar em /tools (por exemplo, -v /path/on/host/to/tools_default:/tools).
Ajuste a tag (:latest) se você baixou uma versão específica.
Defina outras variáveis de ambiente usando o sinalizador -e conforme necessário.

Construindo a imagem localmente (opcional):

docker build -t mcp-proxy-server .

(Se você construir localmente, use mcp-proxy-server em vez do nome da imagem ghcr.io/... no comando docker run acima).

Instalação e uso com clientes

Este servidor proxy pode ser usado de duas maneiras principais:

1. Como um servidor MCP Stdio: Configure seu cliente MCP (como Claude Desktop) para executar o servidor proxy diretamente usando seu comando (build/index.js). O proxy então se conectará aos servidores backend definidos em seu config/mcp_server.json.

Exemplo para Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-proxy": {
      "name": "MCP Proxy (Aggregator)",
      "command": "/path/to/mcp-proxy-server/build/index.js",
      "env": {
         "NODE_ENV": "production", // Optional: Set environment for the proxy itself
         "TOOLS_FOLDER": "/custom/path/for/proxy/tools" // Optional: If proxy needs to install its own backends
      }
    }
  }
}

Substitua /path/to/mcp-proxy-server/build/index.js pelo caminho real para o ponto de entrada compilado deste projeto de servidor proxy. Certifique-se de que o diretório config esteja localizado corretamente em relação ao local onde o comando é executado, ou use caminhos absolutos na configuração do próprio proxy, se necessário.

2. Como um servidor MCP SSE ou HTTP Streamable: Execute o servidor proxy em um modo que inicie seu servidor HTTP (por exemplo, npm run dev:sse ou o contêiner Docker). Em seguida, configure seu cliente MCP para se conectar ao endpoint apropriado do proxy: - Para SSE: http://localhost:3663/sse - Para HTTP Streamable: http://localhost:3663/mcp

Se a autenticação estiver habilitada no proxy (via ALLOWED_KEYS ou ALLOWED_TOKENS), o cliente precisará fornecer as credenciais correspondentes.

Métodos de autenticação (para /sse e /mcp):

Chave de API: Forneça a chave na configuração do cliente. Para o endpoint /sse, o parâmetro de consulta de URL ?key=... é suportado. Para ambos /sse e /mcp, o cabeçalho X-Api-Key é suportado.
Token Bearer: Defina o cabeçalho Authorization: Bearer <token> na configuração do cliente.

Exemplo para Claude Desktop (claude_desktop_config.json) conectando-se a SSE:

{
  "mcpServers": {
    "my-proxy-sse": {
      "type": "sse", // Important for clients that distinguish
      "name": "MCP Proxy (SSE)",
      // If using API Key authentication, append ?key=<your_key>
      "url": "http://localhost:3663/sse?key=clientkey1"
      // If using Bearer Token authentication, the client configuration method may vary.
      // For example, some clients might support setting custom headers:
      // "headers": {
      //   "Authorization": "Bearer your_bearer_token_1"
      // }
    }
  }
}

Exemplo para uma configuração genérica de cliente HTTP Streamable:

{
  "mcpServers": {
    "my-proxy-http": {
      "type": "http", // Or the client's specific designation
      "name": "MCP Proxy (Streamable HTTP)",
      "url": "http://localhost:3663/mcp",
      // Authentication headers would be configured according to the client's capabilities
      // e.g., "requestInit": { "headers": { "X-Api-Key": "clientkey1" } }
    }
  }
}

Depuração

Use o MCP Inspector para depurar a comunicação (principalmente para o modo Stdio):

npm run inspector

Este script envolve a execução do servidor compilado (build/index.js) com o inspector. Acesse a interface do inspector via a URL fornecida na saída do console. Para o modo SSE, as ferramentas padrão de desenvolvedor do navegador podem ser usadas para inspecionar solicitações de rede.

Referência

Este projeto foi originalmente inspirado e refatorado a partir de adamwattis/mcp-proxy-server.

MCP Proxy Server

Documentação

MCP Proxy Server

✨ Destaques dos Principais Recursos

Recursos

Gerenciamento de Recursos e Ferramentas via Proxy

✨ Admin UI Web Opcional (ENABLE_ADMIN_UI=true)

Configuração

1. Conexões de Servidores (config/mcp_server.json)

2. Configuração de Ferramentas (config/tool_config.json)

3. Variáveis de Ambiente

Recursos de Confiabilidade Aprimorada

1. Propagação de Erros

2. Tentativa de Repetição de Chamadas de Ferramentas SSE

3. Repetição de Solicitações HTTP para Chamadas de Ferramentas

4. Repetição de Conexão Stdio para Chamadas de Ferramentas

Desenvolvimento

1. Propagação de Erros

2. Repetição de Conexão SSE para Chamadas de Ferramentas

3. Repetição de Solicitações HTTP para Chamadas de Ferramentas

4. Repetição de conexão Stdio para chamadas de ferramentas

Desenvolvimento

Executando com Docker

Instalação e uso com clientes

Depuração

Referência

✨ Admin UI Web Opcional (`ENABLE_ADMIN_UI=true`)

1. Conexões de Servidores (`config/mcp_server.json`)

2. Configuração de Ferramentas (`config/tool_config.json`)