`mcp-remote`

Collega un client MCP che supporta solo server locali (stdio) a un server MCP remoto, con supporto per l'autenticazione:

Nota: questo è un proof-of-concept funzionante ma dovrebbe essere considerato sperimentale.

Perché è necessario?

Finora, la maggior parte dei server MCP in circolazione sono installati localmente, utilizzando il trasporto stdio. Questo ha alcuni vantaggi: sia il client che il server possono fidarsi implicitamente l'uno dell'altro poiché l'utente ha concesso a entrambi il permesso di eseguirli. L'aggiunta di segreti come le chiavi API può essere fatta usando variabili d'ambiente che non lasciano mai la tua macchina. Inoltre, basarsi su npx e uvx ha permesso agli utenti di evitare anche passaggi di installazione espliciti.

Ma c'è un motivo per cui la maggior parte dei software che potevano essere spostati sul web lo sono stati: è molto più facile trovare e correggere bug & iterare su nuove funzionalità quando puoi inviare aggiornamenti a tutti i tuoi utenti con un singolo deploy.

Con l'ultima specifica di autorizzazione di MCP, ora abbiamo un modo sicuro per condividere i nostri server MCP con il mondo senza eseguire codice sui laptop degli utenti. O almeno, lo avresti, se tutti i popolari client MCP lo supportassero già. La maggior parte sono solo stdio, e quelli che supportano HTTP+SSE non supportano ancora i flussi OAuth richiesti.

È qui che entra in gioco mcp-remote. Non appena il client MCP che hai scelto supporta server remoti e autorizzati, puoi rimuoverlo. Fino ad allora, inserisci questa riga e preparati per i client MCP che desideri!

Utilizzo

Tutti i client MCP più popolari (Claude Desktop, Cursor e Windsurf) usano il seguente formato di configurazione:

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

Intestazioni personalizzate

Per bypassare l'autenticazione, o per emettere intestazioni personalizzate su tutte le richieste al tuo server remoto, passa argomenti 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) hanno un bug per cui gli spazi all'interno di args non vengono escaped quando invocano npx, il che finisce per alterare questi valori. Puoi aggirarlo 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
  }
},

Flag

Se npx produce errori, considera di aggiungere -y come primo argomento per accettare automaticamente l'installazione del pacchetto mcp-remote.

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

Per forzare npx a controllare sempre una versione aggiornata di mcp-remote, aggiungi il flag @latest:

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

Per cambiare la porta su cui mcp-remote ascolta per un reindirizzamento OAuth (di default 3334), aggiungi un argomento aggiuntivo dopo l'URL del server. Nota che qualunque porta specifichi, se non è disponibile, verrà scelta una porta libera a caso.

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

Per cambiare l'host che mcp-remote registra come URL di callback OAuth (di default localhost), aggiungi il flag --host.

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

Per consentire connessioni HTTP in reti private fidate, aggiungi il flag --allow-http. Nota: Questo dovrebbe essere usato solo in reti private sicure dove il traffico non può essere intercettato.

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

Per abilitare log di debug dettagliati, aggiungi il flag --debug. Questo scriverà log dettagliati in ~/.mcp-auth/{server_hash}_debug.log con timestamp e informazioni dettagliate sul processo di autenticazione, connessioni e aggiornamento dei token.

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

Per abilitare un proxy HTTP(S) in uscita per mcp-remote, aggiungi il flag --enable-proxy. Quando abilitato, mcp-remote utilizzerà le impostazioni proxy dalle variabili d'ambiente comuni (ad esempio 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"
    }

Per ignorare strumenti specifici dal server remoto, aggiungi il flag --ignore-tool. Questo filtrerà gli strumenti che corrispondono ai pattern specificati sia dalle risposte tools/list sia bloccando le richieste tools/call. Supporta pattern wildcard con *.

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

Puoi specificare più flag --ignore-tool per ignorare pattern diversi. Esempi:

delete* - ignora tutti gli strumenti che iniziano con "delete" (es. deleteTask, deleteUser)
*account - ignora tutti gli strumenti che terminano con "account" (es. getAccount, updateAccount)
exactTool - ignora solo lo strumento chiamato esattamente "exactTool"

Per cambiare il timeout per il callback OAuth (di default 30 secondi), aggiungi il flag --auth-timeout con un valore in secondi. Questo è utile se il processo di autenticazione lato server richiede molto tempo.

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

Strategie di trasporto

MCP Remote supporta diverse strategie di trasporto quando si connette a un server MCP. Questo ti permette di controllare se utilizza Server-Sent Events (SSE) o trasporto HTTP, e in quale ordine li prova.

Specifica la strategia di trasporto con il flag --transport:

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

Strategie disponibili:

http-first (default): Prova prima il trasporto HTTP, passa a SSE se HTTP fallisce con un errore 404
sse-first: Prova prima il trasporto SSE, passa a HTTP se SSE fallisce con un errore 405
http-only: Usa solo il trasporto HTTP, fallisce se il server non lo supporta
sse-only: Usa solo il trasporto SSE, fallisce se il server non lo supporta

Metadati client OAuth statici

MCP Remote supporta la fornitura di metadati client OAuth statici invece di usare i valori predefiniti di mcp-remote. Questo è utile quando ci si connette a server OAuth che si aspettano ID client/software o scope specifici.

Fornisci i metadati del client come stringa JSON o come percorso file con prefisso @ con il 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'

Informazioni client OAuth statiche

Secondo la specifica, i server sono incoraggiati ma non obbligati a supportare la registrazione dinamica del client OAuth.

Per questi server, MCP Remote supporta la fornitura di informazioni client OAuth statiche in alternativa. Questo è utile quando ci si connette a server OAuth che richiedono client pre-registrati.

Fornisci i metadati del client come stringa JSON o come percorso file con prefisso @ con il 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

Documentazione ufficiale

Per aggiungere un server MCP a Claude Desktop devi modificare il file di configurazione situato in:

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

Se non esiste ancora, potrebbe essere necessario abilitarlo in Impostazioni > Sviluppatore.

Riavvia Claude Desktop per applicare le modifiche al file di configurazione. Dopo il riavvio, dovresti vedere un'icona a forma di martello nell'angolo in basso a destra della casella di input.

Cursor

Documentazione ufficiale. Il file di configurazione si trova in ~/.cursor/mcp.json.

A partire dalla versione 0.48.0, Cursor supporta direttamente server SSE non autenticati. Se il tuo server MCP utilizza il protocollo di autorizzazione OAuth ufficiale di MCP, devi comunque aggiungere un server "command" e chiamare mcp-remote.

Windsurf

Documentazione ufficiale. Il file di configurazione si trova in ~/.codeium/windsurf/mcp_config.json.

Costruire server MCP remoti

Per istruzioni su come costruire e distribuire server MCP remoti, incluso agire come client OAuth valido, consulta le seguenti risorse:

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

In particolare, vedi:

https://github.com/cloudflare/workers-oauth-provider per definire un server OAuth conforme a MCP in Cloudflare Workers
https://github.com/cloudflare/agents/tree/main/examples/mcp per definire un McpAgent usando il framework agents.

Per maggiori informazioni sul test di questi server, vedi anche:

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

Conosci altre risorse che vorresti condividere? Aggiungile a questo Readme e invia una PR!

Risoluzione dei problemi

Cancella la directory `~/.mcp-auth`

mcp-remote memorizza tutte le informazioni sulle credenziali all'interno di ~/.mcp-auth (o ovunque punti la tua variabile MCP_REMOTE_CONFIG_DIR). Se hai problemi persistenti, prova a eseguire:

rm -rf ~/.mcp-auth

Quindi riavvia il client MCP.

Controlla la versione di Node

Assicurati che la versione di Node che hai installato sia 18 o superiore. Claude Desktop utilizzerà la versione di Node del sistema, anche se ne hai una più recente installata altrove.

Riavvia Claude

Quando modifichi claude_desktop_config.json, può essere utile riavviare completamente Claude

Certificati VPN

Potresti incontrare problemi se sei dietro una VPN; puoi provare a impostare la variabile d'ambiente NODE_EXTRA_CA_CERTS per puntare al file del certificato CA. Se usi claude_desktop_config.json, potrebbe apparire così:

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

Controlla i log

Segui i log di Claude Desktop in tempo reale
macOS / Linux:
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
Per bash su 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

Debug

Log di debug

Per risolvere problemi complessi, specialmente con l'aggiornamento dei token o problemi di autenticazione, usa il flag --debug:

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

Questo crea log dettagliati in ~/.mcp-auth/{server_hash}_debug.log con timestamp e informazioni complete su ogni fase del processo di connessione e autenticazione. Quando riscontri problemi con l'aggiornamento dei token, problemi di sospensione/ripristino del laptop o problemi di autenticazione, fornisci questi log quando cerchi supporto.

Errori di autenticazione

Se incontri il seguente errore, restituito dall'URL /callback:

Authentication Error
Token exchange failed: HTTP 400

Puoi eseguire rm -rf ~/.mcp-auth per cancellare qualsiasi stato e token memorizzati localmente.

Modalità "Client"

Esegui quanto segue dalla riga di comando (non da un server MCP):

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

Questo eseguirà l'intero flusso di autorizzazione e tenterà di elencare gli strumenti e le risorse all'URL remoto. Provalo dopo aver eseguito rm -rf ~/.mcp-auth per vedere se le credenziali obsolete sono il tuo problema, altrimenti si spera che il problema sia più evidente in questi log che in quelli del tuo client MCP.

CVE-2025-6514

Più Popolari