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 :

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 :

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 :

Drapeaux

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

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

• 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.

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

• 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é.

• 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.

• 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).

• 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 *.

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.

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 :

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

MCP Remote prend en charge la fourniture de métadonnées statiques du client OAuth au lieu d'utiliser les valeurs par défaut de mcp-remote. Cela est utile lors de la connexion à des serveurs OAuth qui attendent des identifiants de client/logiciel ou des portées spécifiques.

Fournissez les métadonnées du client sous forme de chaîne JSON ou de chemin de fichier préfixé par @ avec le drapeau --static-oauth-client-metadata :

Informations statiques du client OAuth

Conformément à la spécification, les serveurs sont encouragés mais non obligés à prendre en charge l'enregistrement dynamique du client OAuth.

Pour ces serveurs, MCP Remote prend en charge la fourniture d'informations statiques du client OAuth à la place. Cela est utile lors de la connexion à des serveurs OAuth qui nécessitent des clients pré-enregistrés.

Fournissez les métadonnées du client sous forme de chaîne JSON ou de chemin de fichier préfixé par @ avec le drapeau --static-oauth-client-info :

Claude Desktop

Documentation officielle

Pour ajouter un serveur MCP à Claude Desktop, vous devez modifier le fichier de configuration situé à :

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

S'il n'existe pas encore, vous devrez peut-être l'activer sous Paramètres > Développeur.

Redémarrez Claude Desktop pour prendre en compte les modifications du fichier de configuration. Après le redémarrage, vous devriez voir une icône de marteau dans le coin inférieur droit de la zone de saisie.

Cursor

Documentation officielle. Le fichier de configuration se trouve à ~/.cursor/mcp.json.

Depuis la version 0.48.0, Cursor prend en charge les serveurs SSE non authentifiés directement. Si votre serveur MCP utilise le protocole d'autorisation OAuth officiel de MCP, vous devez toujours ajouter un serveur de type "command" et appeler mcp-remote.

Windsurf

Documentation officielle. Le fichier de configuration se trouve à ~/.codeium/windsurf/mcp_config.json.

Construction de serveurs MCP distants

Pour des instructions sur la construction et le déploiement de serveurs MCP distants, y compris le fait d'agir en tant que client OAuth valide, consultez les ressources suivantes :

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

En particulier, voir :

• https://github.com/cloudflare/workers-oauth-provider pour définir un serveur OAuth compatible MCP dans Cloudflare Workers
• https://github.com/cloudflare/agents/tree/main/examples/mcp pour définir un McpAgent utilisant le framework agents.

Pour plus d'informations sur le test de ces serveurs, voir également :

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

Vous connaissez d'autres ressources que vous aimeriez partager ? Veuillez les ajouter à ce Readme et envoyer une PR !

Dépannage

Vider votre répertoire ~/.mcp-auth

mcp-remote stocke toutes les informations d'identification dans ~/.mcp-auth (ou là où pointe votre variable MCP_REMOTE_CONFIG_DIR). Si vous rencontrez des problèmes persistants, essayez d'exécuter :

Puis redémarrez votre client MCP.

Vérifier votre version de Node

Assurez-vous que la version de Node que vous avez installée est 18 ou supérieure. Claude Desktop utilisera la version système de Node, même si vous avez une version plus récente installée ailleurs.

Redémarrer Claude

Lors de la modification de claude_desktop_config.json, il peut être utile de redémarrer complètement Claude

Certificats VPN

Vous pouvez rencontrer des problèmes si vous êtes derrière un VPN ; vous pouvez essayer de définir la variable d'environnement NODE_EXTRA_CA_CERTS pour pointer vers le fichier de certificat CA. Si vous utilisez claude_desktop_config.json, cela pourrait ressembler à :

Consulter les journaux

• Suivre les journaux de Claude Desktop en temps réel
• MacOS / Linux :
  tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
• Pour bash sur WSL :
  tail -n 20 -f "C:\Users\VotreNomUtilisateur\AppData\Local\Claude\Logs\mcp.log"
• Powershell :
  Get-Content "C:\Users\VotreNomUtilisateur\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Débogage

Journaux de débogage

Pour résoudre des problèmes complexes, en particulier ceux liés au rafraîchissement des jetons ou à l'authentification, utilisez le drapeau --debug :

Cela crée des journaux détaillés dans ~/.mcp-auth/{server_hash}_debug.log avec des horodatages et des informations complètes sur chaque étape du processus de connexion et d'authentification. Lorsque vous rencontrez des problèmes de rafraîchissement de jetons, de mise en veille/réveil de l'ordinateur portable ou d'authentification, fournissez ces journaux lorsque vous demandez de l'aide.

Erreurs d'authentification

Si vous rencontrez l'erreur suivante, renvoyée par l'URL /callback :

Vous pouvez exécuter rm -rf ~/.mcp-auth pour effacer tout état et jeton stockés localement.

Mode "Client"

Exécutez la commande suivante sur la ligne de commande (pas à partir d'un serveur MCP) :

Cela parcourra tout le flux d'autorisation et tentera de lister les outils et ressources à l'URL distante. Essayez cela après avoir exécuté rm -rf ~/.mcp-auth pour voir si des identifiants obsolètes sont votre problème ; sinon, espérons que le problème sera plus évident dans ces journaux que dans ceux de votre client MCP.