MCP Remote

Um proxy remoto para MCP que permite que clientes locais se conectem a servidores remotos via OAuth.

Documentação

Target language: Português (BR) MCP server name to preserve: MCP Remote Markdown chunk: 1/1

Translate natural-language prose in . Keep every MCP_TOKEN*_ placeholder exactly as written, exactly once, without adding, omitting, duplicating, or renumbering placeholders. They will be restored after translation. Do not create new Markdown links. If a placeholder appears as a bare URL in the input, keep it as a bare placeholder and do not wrap it in . If the input does not contain code fence markers, the output must not contain code fence markers. After the translated Markdown document, append a new final line containing exactly MCP_TRANSLATION_DONE.

# `mcp-remote`

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

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

Por que isso é necessário?

Até agora, a maioria dos servidores MCP existentes 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, já que o usuário concedeu permissão para ambos executarem. Adicionar segredos como chaves de API pode ser feito usando variáveis de ambiente e nunca sai da sua máquina. E construir sobre 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 maioria dos softwares que poderiam ser movidos para a web foram movidos 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 maneira 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á suportassem isso. 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 seu cliente MCP escolhido suportar servidores remotos e autorizados, você pode removê-lo. Até lá, use este one-liner e prepare-se para os clientes MCP que deseja!

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"
      ]
    }
  }
}

Headers Personalizados

Para contornar a autenticação, ou para emitir headers 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: Cursor e Claude Desktop (Windows) têm um bug onde espaços dentro de args não são escapados quando invocam npx, o que acaba corrompendo 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
  }
},

Múltiplas Instâncias

Para executar múltiplas instâncias do mesmo servidor remoto com configurações diferentes (por exemplo, diferentes tenants do Atlassian), use a flag --resource para isolar sessões OAuth:

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    },
    "atlassian_tenant2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant2.atlassian.net/"
      ]
    }
  }
}

Cada combinação única de URL do servidor, recurso e headers personalizados manterá sessões OAuth e armazenamento de tokens separados.

Flags

Se npx estiver produzindo erros, considere adicionar -y como 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 npx a sempre verificar se há uma versão atualizada de mcp-remote, adicione a flag @latest:

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

Para alterar em qual porta mcp-remote escuta um redirecionamento OAuth (por padrão 3334), adicione um argumento adicional após a URL do servidor. Observe que, qualquer que seja a 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 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 só deve ser usado em redes privadas seguras onde o tráfego não possa ser interceptado.

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

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

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

Para suprimir logs padrão, adicione a flag --silent. Isso impedirá que logs sejam emitidos, exceto quando --debug também for passado.

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

Para habilitar um proxy HTTP(S) de saída para mcp-remote, adicione a flag --enable-proxy. Quando habilitado, 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á ferramentas que correspondam aos padrões especificados de ambas as respostas tools/list e bloqueará solicitações tools/call. Suporta padrões curinga com *.

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

Você pode especificar múltiplas flags --ignore-tool para ignorar diferentes padrões. Exemplos:

delete* - ignora todas as ferramentas que começam com "delete" (por exemplo, deleteTask, deleteUser)
*account - ignora todas as ferramentas que terminam com "account" (por exemplo, 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 levar muito tempo.

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

Estratégias de Transporte

MCP Remote suporta diferentes estratégias de transporte ao se conectar a um servidor MCP. Isso permite que você controle se ele usa transporte Server-Sent Events (SSE) ou 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 primeiro o transporte HTTP, recorre ao SSE se o HTTP falhar com erro 404
sse-first: Tenta primeiro o transporte SSE, recorre ao HTTP se o SSE falhar com erro 405
http-only: Usa apenas o transporte HTTP, falha se o servidor não suportar
sse-only: Usa apenas o transporte SSE, falha se o servidor não suportar

Metadados Estáticos do Cliente OAuth

MCP Remote suporta fornecer 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 específicos de cliente/software ou escopos.

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

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

Informações Estáticas do Cliente OAuth

De acordo com a especificação, os servidores são incentivados, mas não obrigados, a suportar registro dinâmico de cliente OAuth.

Para esses servidores, MCP Remote suporta fornecer informações estáticas do cliente OAuth em vez disso. Isso é útil ao conectar-se a servidores OAuth que exigem clientes pré-registrados.

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

export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

Documentação Oficial

Para adicionar um servidor MCP ao Claude Desktop, você precisa editar o arquivo de configuração localizado em:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Se ainda não existir, talvez seja necessário habilitá-lo em Settings > Developer.

Reinicie o Claude Desktop para aplicar as alterações no arquivo de configuração. Ao reiniciar, você deve ver um ícone de martelo no canto inferior direito da caixa de entrada.

Cursor

Documentação Oficial. O arquivo de configuração está localizado em ~/.cursor/mcp.json.

A partir da versão 0.48.0, o Cursor suporta servidores SSE sem autenticação diretamente. Se o seu servidor MCP estiver usando o protocolo oficial de autorização OAuth do MCP, você ainda precisará adicionar um servidor "command" e chamar mcp-remote.

Windsurf

Documentação Oficial. O arquivo de configuração está localizado em ~/.codeium/windsurf/mcp_config.json.

Construindo Servidores MCP Remotos

Para instruções sobre como construir e implantar servidores MCP remotos, incluindo atuar como um cliente OAuth válido, consulte os seguintes recursos:

https://developers.cloudflare.com/agents/guides/remote-mcp-server/

Em particular, veja:

https://github.com/cloudflare/workers-oauth-provider para definir um servidor OAuth compatível com MCP no Cloudflare Workers
https://github.com/cloudflare/agents/tree/main/examples/mcp para definir um McpAgent usando o framework agents.

Para mais informações sobre como testar esses servidores, veja também:

https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

Conhece mais recursos que gostaria de compartilhar? Por favor, adicione-os a este Readme e envie um PR!

Solução de Problemas

Limpe seu diretório `~/.mcp-auth`

mcp-remote armazena todas as informações de credenciais dentro de ~/.mcp-auth (ou onde quer que seu MCP_REMOTE_CONFIG_DIR aponte). Se você estiver tendo problemas persistentes, tente executar:

rm -rf ~/.mcp-auth

Em seguida, reinicie seu cliente MCP.

Verifique sua versão do Node

Certifique-se de que a versão do Node que você instalou é 18 ou superior. O Claude Desktop usará a versão do Node do seu sistema, mesmo se você tiver uma versão mais nova instalada em outro lugar.

Reinicie o Claude

Ao modificar o claude_desktop_config.json, pode ser útil reiniciar completamente o Claude

Certificados VPN

Você pode encontrar problemas se estiver atrás de uma VPN; tente definir a variável de ambiente NODE_EXTRA_CA_CERTS para apontar para o arquivo de certificado CA. Se estiver usando claude_desktop_config.json, isso pode ser assim:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

Verifique os logs

Siga os logs do Claude Desktop em tempo real
MacOS / Linux:
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
Para bash no WSL:
tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
Powershell:
Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Depuração

Logs de Depuração

Para solucionar problemas complexos, especialmente com atualização de tokens ou problemas de autenticação, use a flag --debug:

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

Isso cria logs detalhados em ~/.mcp-auth/{server_hash}_debug.log com carimbos de data/hora e informações completas sobre cada etapa do processo de conexão e autenticação. Quando você encontrar problemas com atualização de tokens, problemas de suspensão/retomada do laptop ou problemas de autenticação, forneça esses logs ao buscar suporte.

Erros de Autenticação

Se você encontrar o seguinte erro, retornado pela URL /callback:

Authentication Error
Token exchange failed: HTTP 400

Você pode executar rm -rf ~/.mcp-auth para limpar qualquer estado e tokens armazenados localmente.

Modo "Cliente"

Execute o seguinte na linha de comando (não a partir de um servidor MCP):

npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse

Isso percorrerá todo o fluxo de autorização e tentará listar as ferramentas e recursos na URL remota. Tente isso após executar rm -rf ~/.mcp-auth para ver se credenciais antigas são o seu problema; caso contrário, esperamos que o problema seja mais óbvio nesses logs do que nos logs do seu cliente MCP.