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: