mcp-remote

Connectez un client MCP qui ne prend en charge que les serveurs locaux (stdio) à un serveur MCP distant, avec prise en charge de l'authentification :

Remarque : il s'agit d'une preuve de concept fonctionnelle mais doit être considérée comme expérimentale.

Pourquoi est-ce nécessaire ?

Jusqu'à présent, la majorité des serveurs MCP dans la nature sont installés localement, en utilisant le transport stdio. Cela présente certains avantages : le client et le serveur peuvent implicitement se faire confiance car l'utilisateur leur a accordé à tous deux l'autorisation de s'exécuter. L'ajout de secrets comme les clés API peut se faire via des variables d'environnement et ne quitte jamais votre machine. Et l'utilisation de npx et uvx a également permis aux utilisateurs d'éviter des étapes d'installation explicites.

Mais il y a une raison pour laquelle la plupart des logiciels qui pourraient être déplacés vers le web l'ont été : il est tellement plus facile de trouver et corriger des bugs et d'itérer sur de nouvelles fonctionnalités lorsque vous pouvez déployer des mises à jour à tous vos utilisateurs en un seul déploiement.

Avec la dernière spécification d'autorisation de MCP, nous avons désormais un moyen sécurisé de partager nos serveurs MCP avec le monde sans exécuter de code sur les ordinateurs portables des utilisateurs. Du moins, ce serait le cas, si tous les clients MCP populaires le prenaient déjà en charge. La plupart sont uniquement stdio, et ceux qui supportent HTTP+SSE ne prennent pas encore en charge les flux OAuth requis.

C'est là que mcp-remote intervient. Dès que votre client MCP choisi prend en charge les serveurs distants et autorisés, vous pouvez le supprimer. En attendant, ajoutez cette ligne unique et habillez-vous pour les clients MCP que vous voulez !

Utilisation

Tous les clients MCP les plus populaires (Claude Desktop, Cursor et Windsurf) utilisent le format de configuration suivant :

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

En-têtes personnalisés

Pour contourner l'authentification, ou pour émettre des en-têtes personnalisés sur toutes les requêtes vers votre serveur distant, passez les arguments CLI --header :

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

Remarque : Cursor et Claude Desktop (Windows) ont un bogue où les espaces dans args ne sont pas échappés lors de l'appel à npx, ce qui finit par déformer ces valeurs. Vous pouvez contourner ce problème en utilisant :

{
  // reste de la configuration...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // notez l'absence d'espaces autour de ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // les espaces sont OK dans les variables d'environnement
  }
},

Drapeaux

• Si npx produit des erreurs, pensez à ajouter -y comme premier argument pour accepter automatiquement l'installation du paquet mcp-remote.

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

• Pour forcer npx à toujours vérifier une version mise à jour de mcp-remote, ajoutez le drapeau @latest :

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

• Pour changer le port sur lequel mcp-remote écoute pour une redirection OAuth (par défaut 3334), ajoutez un argument supplémentaire après l'URL du serveur. Notez que quel que soit le port spécifié, s'il est indisponible, un port ouvert sera choisi aléatoirement.

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

• Pour changer l'hôte que mcp-remote enregistre comme URL de rappel OAuth (par défaut localhost), ajoutez le drapeau --host.

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

• Pour autoriser les connexions HTTP dans les réseaux privés de confiance, ajoutez le drapeau --allow-http. Remarque : Cela ne doit être utilisé que dans des réseaux privés sécurisés où le trafic ne peut pas être intercepté.

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

• Pour activer les journaux de débogage détaillés, ajoutez le drapeau --debug. Cela écrira des journaux verbeux dans ~/.mcp-auth/{server_hash}_debug.log avec des horodatages et des informations détaillées sur le processus d'authentification, les connexions et le rafraîchissement des jetons.

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

• Pour activer un proxy HTTP(S) sortant pour mcp-remote, ajoutez le drapeau --enable-proxy. Lorsqu'il est activé, mcp-remote utilisera les paramètres de proxy des variables d'environnement courantes (par exemple HTTP_PROXY, HTTPS_PROXY, et 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"
    }

• Pour ignorer des outils spécifiques du serveur distant, ajoutez le drapeau --ignore-tool. Cela filtrera les outils correspondant aux motifs spécifiés des réponses tools/list et bloquera les requêtes tools/call. Prend en charge les motifs génériques avec *.

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

Vous pouvez spécifier plusieurs drapeaux --ignore-tool pour ignorer différents motifs. Exemples :

• delete* - ignore tous les outils commençant par "delete" (par exemple, deleteTask, deleteUser)
• *account - ignore tous les outils se terminant par "account" (par exemple, getAccount, updateAccount)
• exactTool - ignore uniquement l'outil nommé exactement "exactTool"

• Pour changer le délai d'attente du rappel OAuth (par défaut 30 secondes), ajoutez le drapeau --auth-timeout avec une valeur en secondes. Cela est utile si le processus d'authentification côté serveur prend beaucoup de temps.

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

Stratégies de transport

MCP Remote prend en charge différentes stratégies de transport lors de la connexion à un serveur MCP. Cela vous permet de contrôler s'il utilise le transport SSE (Server-Sent Events) ou HTTP, et dans quel ordre il les essaie.

Spécifiez la stratégie de transport avec le drapeau --transport :

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

Stratégies disponibles :

• http-first (par défaut) : Essaie d'abord le transport HTTP, puis bascule vers SSE si HTTP échoue avec une erreur 404
• sse-first : Essaie d'abord le transport SSE, puis bascule vers HTTP si SSE échoue avec une erreur 405
• http-only : Utilise uniquement le transport HTTP, échoue si le serveur ne le prend pas en charge
• sse-only : Utilise uniquement le transport SSE, échoue si le serveur ne le prend pas en charge

Métadonnées statiques du client OAuth