mcp-remote

Conecte um Cliente MCP que só suporta servidores locais (stdio) a um Servidor MCP Remoto, com suporte a autenticação:

Nota: isto é uma prova de conceito funcional, mas deve ser considerado experimental.

Por que isto é necessário?

Até agora, a maioria dos servidores MCP encontrados por aí são instalados localmente, usando o transporte stdio. Isso tem alguns benefícios: tanto o cliente quanto o servidor podem confiar implicitamente um no outro, uma vez que o usuário concedeu a ambos permissão para executar. Adicionar segredos como chaves de API pode ser feito usando variáveis de ambiente e eles nunca saem da sua máquina. E construir com base em npx e uvx também permitiu que os usuários evitassem etapas explícitas de instalação.

Mas há uma razão pela qual a maior parte do software que poderia ser movido para a web foi movida para a web: é muito mais fácil encontrar e corrigir bugs e iterar em novos recursos quando você pode enviar atualizações para todos os seus usuários com uma única implantação.

Com a mais recente especificação de Autorização do MCP, agora temos uma forma segura de compartilhar nossos servidores MCP com o mundo sem executar código nos laptops dos usuários. Ou, pelo menos, você teria, se todos os clientes MCP populares já a suportassem. A maioria é apenas stdio, e aqueles que suportam HTTP+SSE ainda não suportam os fluxos OAuth necessários.

É aí que entra o mcp-remote. Assim que o cliente MCP de sua escolha suportar servidores remotos autorizados, você pode removê-lo. Até lá, insira este one-liner e prepare-se para os clientes MCP que você quiser!

Uso

Todos os clientes MCP mais populares (Claude Desktop, Cursor e Windsurf) usam o seguinte formato de configuração:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

Cabeçalhos Personalizados

Para contornar a autenticação ou emitir cabeçalhos personalizados em todas as solicitações ao seu servidor remoto, passe os argumentos de CLI --header:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

Nota: O Cursor e o Claude Desktop (Windows) têm um bug em que espaços dentro de args não são escapados quando ele invoca o npx, o que acaba danificando esses valores. Você pode contornar isso usando:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

Flags

• Se o npx estiver gerando erros, considere adicionar -y como o primeiro argumento para aceitar automaticamente a instalação do pacote mcp-remote.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• Para forçar o npx a sempre verificar se há uma versão atualizada do mcp-remote, adicione a flag @latest:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• Para alterar em qual porta o mcp-remote escuta um redirecionamento OAuth (por padrão, 3334), adicione um argumento adicional após a URL do servidor. Observe que, independentemente da porta especificada, se ela não estiver disponível, uma porta aberta será escolhida aleatoriamente.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• Para alterar qual host o mcp-remote registra como URL de callback OAuth (por padrão, localhost), adicione a flag --host.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• Para permitir conexões HTTP em redes privadas confiáveis, adicione a flag --allow-http. Nota: Isso deve ser usado apenas em redes privadas seguras, onde o tráfego não pode ser interceptado.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• Para habilitar logs de depuração detalhados, adicione a flag --debug. Isso gravará logs detalhados em ~/.mcp-auth/{server_hash}_debug.log com registros de data e hora e informações detalhadas sobre o processo de autenticação, conexões e renovação de tokens.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• Para habilitar um proxy HTTP(S) de saída para o mcp-remote, adicione a flag --enable-proxy. Quando habilitado, o mcp-remote usará as configurações de proxy de variáveis de ambiente comuns (por exemplo, HTTP_PROXY, HTTPS_PROXY e NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• Para ignorar ferramentas específicas do servidor remoto, adicione a flag --ignore-tool. Isso filtrará as ferramentas que correspondem aos padrões especificados tanto nas respostas de tools/list quanto bloqueará solicitações de tools/call. Suporta padrões curinga com *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

Você pode especificar várias flags --ignore-tool para ignorar padrões diferentes. Exemplos:

• delete* - ignora todas as ferramentas que começam com "delete" (ex.: deleteTask, deleteUser)
• *account - ignora todas as ferramentas que terminam com "account" (ex.: getAccount, updateAccount)
• exactTool - ignora apenas a ferramenta chamada exatamente "exactTool"

• Para alterar o tempo limite do callback OAuth (por padrão, 30 segundos), adicione a flag --auth-timeout com um valor em segundos. Isso é útil se o processo de autenticação no lado do servidor demorar muito.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

Estratégias de Transporte

O MCP Remote suporta diferentes estratégias de transporte ao conectar-se a um servidor MCP. Isso permite controlar se ele usa Server-Sent Events (SSE) ou transporte HTTP, e em que ordem tenta cada um.

Especifique a estratégia de transporte com a flag --transport:

npx mcp-remote https://example.remote/server --transport sse-only

Estratégias disponíveis:

• http-first (padrão): tenta o transporte HTTP primeiro e recorre ao SSE se o HTTP falhar com erro 404
• sse-first: tenta o transporte SSE primeiro e recorre ao HTTP se o SSE falhar com erro 405
• http-only: usa apenas o transporte HTTP; falha se o servidor não o suportar
• sse-only: usa apenas o transporte SSE; falha se o servidor não o suportar

Metadados Estáticos do Cliente OAuth

O MCP Remote suporta o fornecimento de metadados estáticos do cliente OAuth em vez de usar os padrões do mcp-remote. Isso é útil ao conectar-se a servidores OAuth que esperam IDs ou escopos específicos de cliente/software.

Forneça os metadados do cliente como uma string JSON ou como um caminho de arquivo com prefixo @ usando a flag --static-oauth-client-metadata: