OpenAPI Explorer:Proxy an OpenAPI MCP server using aliyun mcp-proxy

Étape 1 : Configurer Alibaba Cloud CLI

1. Installez ou mettez à jour Alibaba Cloud CLI vers la version 3.5.0 ou ultérieure. Pour obtenir des instructions, consultez la rubrique Installation, mise à jour et désinstallation d'Alibaba Cloud CLI.

2. Configurez la CLI avec la paire AccessKey d'un compte Alibaba Cloud ou d'un utilisateur RAM.

   aliyun configure
   # Enter the AccessKey ID, AccessKey secret, and default region as prompted.

   Si vous utilisez un utilisateur RAM, accordez-lui les autorisations indiquées dans le tableau suivant.

   Autorisation	Objectif	Scénarios
   ram:ListApplications	Interroge les applications OAuth par nom.	Obligatoire. Le proxy a besoin de cette autorisation au premier démarrage, ou lorsque les informations d'autorisation enregistrées localement ne sont pas disponibles. Cette autorisation est également requise lorsque vous utilisez --oauth-app-name pour spécifier une application existante.
   ram:CreateApplication	Crée l'application OAuth par défaut aliyun-cli-mcp-proxy.	Requis lorsque vous n'utilisez pas --oauth-app-name pour spécifier une application et que l'application par défaut n'existe pas.
   ram:GetApplication	Interroge les applications OAuth par ID.	Recommandé. Le proxy utilise cette autorisation pour réutiliser les informations d'autorisation enregistrées localement. Sans cette autorisation, le proxy doit effectuer une nouvelle autorisation OAuth à chaque démarrage.

Étape 2 : Exécuter le proxy pour la première fois et effectuer l'autorisation OAuth

Lorsque vous exécutez mcp-proxy pour la première fois, vous devez effectuer une autorisation OAuth unique pour obtenir l'autorisation d'actualiser les jetons.

1. Démarrez le proxy au premier plan.

   • Dans un environnement doté d'une interface graphique, si vous n'ajoutez pas le paramètre --no-browser, la CLI ouvre automatiquement un navigateur pour exécuter le flux de connexion d'autorisation OAuth, et vous n'avez pas besoin de saisir manuellement le code d'autorisation. Une fois l'autorisation terminée, passez à l'étape 5.

     aliyun utils mcp-proxy --host 127.0.0.1 --port 8088

   • Sur un serveur sans interface graphique, ajoutez le paramètre --no-browser. Les étapes suivantes vous guident pour obtenir manuellement le code d'autorisation.

     aliyun utils mcp-proxy --host 127.0.0.1 --port 8088 --no-browser

   Remarque

   Vous pouvez utiliser le paramètre --oauth-app-name pour spécifier une application OAuth personnalisée. L'application doit répondre aux exigences suivantes :

   • Portée OAuth : Inclut la portée d'autorisation spécifiée par le paramètre --scope. La valeur par défaut est /acs/mcp-server.

   • URI de redirection : Inclut http://<host>:<port>/callback, où host et port correspondent aux valeurs des paramètres --host et --port que vous utilisez pour démarrer le proxy.

   • Type d'application : Doit être une application NativeApp.

2. Le terminal affiche l'URL d'autorisation.

   Setting up MCPOAuth profile 'default-mcp'...
   Opening browser for OAuth login...
   URL: https://signin.alibabacloud.com/oauth2/v1/auth?client_id=XXXX&response_type=code&scope=%2Facs%2Fmcp-server&redirect_uri=http://127.0.0.1:8088/callback&code_challenge=XXX&code_challenge_method=S256
   Please open the authorization URL on a machine with a browser and complete the sign-in.
   After authorization, the browser will redirect to a callback URL.
   Even if the page fails to load (connection error), the authorization code is in the URL.
   Please copy the value of the `code` parameter from the browser's address bar.
   Example: If the URL is:
     http://127.0.0.1:8088/callback?code=abc123xyz&state=...
     Then copy only: abc123xyz
   Enter authorization code: <YOUR CODE>

3. Ouvrez l'URL dans un navigateur, connectez-vous et terminez l'autorisation.

4. Une fois l'autorisation réussie, la page redirige vers une adresse contenant le paramètre code, ou affiche directement le code d'autorisation. Copiez la valeur de code, collez-la dans le terminal et appuyez sur Entrée pour confirmer.

5. Lorsque le terminal affiche le message OAuth login successful!, la connexion d'autorisation a réussi.

   2025/12/04 19:11:49 OAuth authorization code received successfully
   2025/12/04 19:11:49 Start to exchange code for token with PKCE
   2025/12/04 19:11:49 Exchange code for token with PKCE successfully
   OAuth login successful!

6. Lorsque le terminal affiche le message MCP Proxy Server Started, le proxy démarre correctement.

   MCP Profile 'default-mcp' configured for oauth app 'aliyun-cli-mcp-proxy' successfully!
   
   MCP Proxy Server Started
   Listen: 127.0.0.1:8088
   Region: CN

Étape 3 : Configurer un service d'arrière-plan systemd (exemple CentOS)

Pour assurer un fonctionnement stable du proxy, configurez-le en tant que service systemd qui démarre au boot.

1. Créez le fichier de service systemd : aliyun-mcp-proxy.

   Remplacez le contenu suivant :

   • Remplacez your-user dans la commande par le nom d'utilisateur réel non-root qui exécute cette commande. Cet utilisateur doit avoir configuré les identifiants en exécutant aliyun configure, et doit avoir effectué l'autorisation OAuth précédente sous cet utilisateur. Au démarrage du service, il réutilise les identifiants d'autorisation enregistrés dans le répertoire personnel de cet utilisateur et ne déclenche pas à nouveau l'autorisation via le navigateur.

   • ExecStart doit contenir le chemin absolu de la commande aliyun. Exécutez which aliyun pour obtenir le chemin réel, et remplacez /usr/local/bin/aliyun dans l'exemple. systemd n'analyse pas ce champ via un shell, donc la substitution de commande telle que $(which aliyun) ne prend pas effet.

   sudo tee /etc/systemd/system/aliyun-mcp-proxy.service << 'EOF'
   [Unit]
   Description=Aliyun CLI MCP Proxy
   After=network.target
   [Service]
   Type=simple
   User=your-user
   ExecStart=/usr/local/bin/aliyun utils mcp-proxy --host 127.0.0.1 --port 8088 --no-browser
   Restart=always
   RestartSec=10
   Environment=HOME=/home/your-user
   [Install]
   WantedBy=multi-user.target
   EOF

2. Rechargez la configuration systemd et démarrez le service.

   # Reload the configuration
   sudo systemctl daemon-reload
   # Start the service
   sudo systemctl start aliyun-mcp-proxy
   # Enable the service to start on boot
   sudo systemctl enable aliyun-mcp-proxy

Étape 4 : Vérifier le service proxy

Vérifiez que le service fonctionne correctement en utilisant l'une des méthodes suivantes.

• Afficher l'état du service

  Exécutez la commande suivante pour afficher l'état du service.

  sudo systemctl status aliyun-mcp-proxy

  Si la sortie contient active (running), le service a démarré avec succès.

• Interroger le port du proxy

  Exécutez la commande suivante pour envoyer une requête directement au port du proxy.

  curl http://127.0.0.1:8088/

  Si le proxy fonctionne correctement, vous recevez une réponse d'erreur XML du serveur MCP, ce qui indique que la connexion entre le proxy et le service est établie.

  <?xml version='1.0' encoding='UTF-8'?><Error><RequestId>B3311876-XXXXX</RequestId><HostId>openapi-mcp.cn-hangzhou.aliyuncs.com</HostId><Code>InvalidAction.NotFound</Code><Message>Specified api is not found, please check your url and method.</Message><Recommend><![CDATA[https://api.alibabacloud.com/troubleshoot?q=InvalidAction.NotFound&product=OpenAPIExplorer&requestId=B3311876-XXX]]></Recommend></Error>

Étape 1 : Obtenir l'adresse IP du pont Docker de l'hôte et démarrer le service mcp-proxy

Le conteneur Dify doit accéder au service mcp-proxy via l'adresse IP du pont Docker de l'hôte.

1. Exécutez la commande suivante pour obtenir et noter l'adresse IP.

   ip addr show docker0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1

   La commande renvoie une adresse IP telle que 172.17.0.1.

2. Démarrez le service mcp-proxy au premier plan. Alternativement, modifiez la commande de démarrage dans systemd puis démarrez le service.

   aliyun utils mcp-proxy --host 172.17.0.1 --port 8088 --no-browser

   Remarque

   L'adresse de rappel est déterminée à la fois par les paramètres --host et --port. Après avoir changé l'adresse d'écoute de 127.0.0.1 à l'adresse IP du pont Docker, ajoutez la nouvelle adresse de rappel (par exemple, http://172.17.0.1:8088/callback) à l'application OAuth correspondante sous Integrations > OAuth Applications (Public Preview) dans la console RAM. Sinon, le démarrage échoue car l'adresse de rappel ne passe pas la validation.

Étape 2 : Configurer le serveur MCP dans Dify

1. Accédez à la page de configuration Tools > MCP dans Dify.

2. Cliquez sur Add MCP Server (HTTP).

3. Dans le champ Server Endpoint URL, saisissez l'adresse du proxy MCP.

   Dans la console Alibaba Cloud OpenAPI MCP Service, obtenez l'adresse originale Streamable HTTP Endpoint , et remplacez la partie domaine (hôte) de l'adresse par votre adresse de proxy locale ou interne.

   Exemple de conversion :

   • Endpoint original : https://openapi-mcp.cn-hangzhou.aliyuncs.com/accounts/1234/custom/cli-proxy-test/id/1234/mcp

   • Remplacer par l'adresse du proxy (en supposant que le proxy s'exécute sur 172.17.0.1:8088) : http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. Remplissez les autres informations selon vos besoins et cliquez sur Add & Authorize. Dify communique avec le service MCP via cette adresse de proxy.

Mesures d'atténuation

• Isolation de l'environnement — Exécutez le proxy uniquement dans un environnement de confiance à utilisateur unique, et évitez de l'utiliser sur des serveurs partagés multi-utilisateurs.

• Contrôle d'accès réseau — Liez l'adresse d'écoute du proxy (--host) à 127.0.0.1 (par défaut) ou à une adresse IP interne spécifique. Utilisez des règles de pare-feu ou de groupe de sécurité pour limiter la portée d'accès du port du proxy (par exemple, autoriser l'accès uniquement depuis des adresses IP de serveurs d'application spécifiques), et n'exposez jamais le port à Internet.

• Contrôle d'accès — Utilisez le paramètre --allowed-servers ou --blocked-servers pour limiter la portée des serveurs MCP accessibles et empêcher l'utilisation du proxy pour accéder à des services non désirés. Pour obtenir des instructions, consultez la section Configurer le contrôle d'accès au serveur.

• Principe du moindre privilège — Configurez un accès avec le moindre privilège pour l'utilisateur CLI utilisé par le proxy et les serveurs MCP associés. Accordez d'abord des autorisations en lecture seule.

• Audit et surveillance — Consultez régulièrement les journaux d'accès du service proxy et surveillez les requêtes anormales. Les requêtes bloquées par le contrôle d'accès sont enregistrées dans les journaux du proxy.

Configurer le contrôle d'accès au serveur

aliyun utils mcp-proxy prend en charge les mécanismes de liste blanche et de liste noire pour limiter la portée des serveurs MCP accessibles via le proxy.

Available Servers:
  - cloudphone
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/eds-aic/cloudphone/id/XSkb9v4dXx000000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/eds-aic/cloudphone/id/XSkb9v4dXx000000/sse
  - multi_account
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/custom/multi_account/id/OV0Qkpxh0Uodx000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/custom/multi_account/id/OV0Qkpxh0Uodx000/sse

......./system/eds-aic/$server_name/id/$server_id/mcp
......./custom/$server_name/id/$server_id/mcp

aliyun utils mcp-proxy --allowed-servers "ecs-basic,oss-basic" --blocked-servers "oss-basic"

MCP Proxy Server Started
Listen: 127.0.0.1:8088
Region: CN

Access Control:
  Blacklist (blocked servers):
    - oss-basic
  Whitelist (allowed servers):
    - ecs-basic
    - oss-basic

Available Servers:
  - ecs-basic
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Ecs/ecs-basic/id/daRi22dx71iX0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Ecs/ecs-basic/id/daRi22dx71iX0000/sse
  - oss-basic (blocked)
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/sse
  - cms-basic (not in whitelist)
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/sse

Press Ctrl+C to stop

MCP Proxy access denied: path /accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/mcp is in blocked servers list
MCP Proxy access denied: path /accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/mcp is not in allowed servers list

Réponse aux incidents de sécurité

Si vous soupçonnez que le jeton d'authentification du proxy a été divulgué ou utilisé de manière abusive, effectuez immédiatement les opérations suivantes :

• Arrêtez le service mcp-proxy.

• Supprimez le fichier de configuration local : rm ~/.aliyun/.mcpproxy_config.

• Supprimez l'application OAuth pour invalider définitivement le jeton d'actualisation divulgué. Connectez-vous à la console RAM en tant qu'administrateur RAM. Dans le volet de navigation de gauche, choisissez Integrations > OAuth Applications (Public Preview). Sous l'onglet Enterprise Applications, cliquez sur Delete Application dans la colonne Actions de l'application cible. Vous pouvez également utiliser la CLI pour supprimer l'application. Après la suppression, lorsque vous effectuez à nouveau l'autorisation OAuth, la CLI crée automatiquement une nouvelle application.

  aliyun ims list-applications --cli-query "Applications.Application[?AppName=='aliyun-cli-mcp-proxy'].AppId"
  aliyun ims delete-application --app-id <Application ID>

• Consultez les journaux d'appels API pour confirmer l'existence d'opérations anormales.

• Redémarrez le proxy et effectuez l'autorisation OAuth pour obtenir un nouveau jeton.

Après avoir exécuté aliyun utils mcp-proxy pour l'authentification OAuth, l'erreur « ERROR: OAuth flow returned empty RefreshToken » apparaît et le proxy ne démarre pas. Pourquoi ?

Cette erreur indique que l'application OAuth actuellement utilisée n'est pas une application NativeApp, elle ne peut donc pas renvoyer de jeton d'actualisation dans le flux d'autorisation. Traitez le problème de l'une des manières suivantes :

• Supprimez l'application OAuth, puis redémarrez le proxy. La CLI crée automatiquement une application NativeApp.

• Créez manuellement une application NativeApp, et spécifiez l'application en utilisant --oauth-app-name lorsque vous démarrez le proxy.

Que faire si l'erreur « failed to find OAuth application » apparaît avec le code d'erreur NoPermission lors du démarrage du proxy ?

Exemple d'erreur :

ERROR: failed to find OAuth application 'aliyun-cli-mcp-proxy': SDKError:
   StatusCode: 401
   Code: NoPermission
   Message: code: 401, The user has no permission
   Data: {"AccessDeniedDetail":{"AuthAction":"ram:ListApplications","AuthPrincipalType":"SubUser", ...}}

Lors de la phase de démarrage, le proxy doit interroger ou créer une application OAuth, et cette opération est effectuée en utilisant les identifiants Alibaba Cloud CLI. L'erreur ci-dessus indique que l'utilisateur RAM correspondant aux identifiants CLI actuels n'a pas reçu l'autorisation spécifiée par le champ AuthAction (ram:ListApplications dans cet exemple).

Traitez le problème de l'une des manières suivantes :

• Accordez les autorisations requises à l'utilisateur RAM. Pour plus d'informations, consultez la section Étape 1 : Configurer Alibaba Cloud CLI.

• Exécutez le proxy en utilisant des identifiants disposant des autorisations requises, tels qu'un compte Alibaba Cloud ou un autre utilisateur RAM ayant terminé l'autorisation.

Que faire si le démarrage échoue avec l'erreur « does not have required redirect URI » après avoir modifié --host ou --port ?

L'application OAuth doit contenir l'adresse de rappel correspondant au démarrage actuel. La modification de --host ou de --port modifie cette adresse. Exemple d'erreur :

ERROR: OAuth application validation failed: OAuth application 'aliyun-cli-mcp-proxy' does not have required redirect URI 'http://172.17.0.1:8088/callback'. Available redirect URIs: [http://127.0.0.1:8088/callback]

Connectez-vous à la console RAM en tant qu'administrateur RAM. Dans le volet de navigation de gauche, choisissez Integrations > OAuth Applications (Public Preview). Sous l'onglet Enterprise Applications, cliquez sur le nom de l'application cible. Dans la section Basic Information, cliquez sur Edit, et ajoutez l'adresse indiquée par required redirect URI dans le message d'erreur aux adresses de rappel. La même application peut conserver plusieurs adresses de rappel, et les adresses existantes restent disponibles après l'ajout d'une nouvelle.

Que faire si « Connection Refused » ou « Timeout » apparaît après avoir configuré le proxy dans Dify ?

Vérifiez les deux points suivants :

1. Lors du démarrage du service mcp-proxy, vérifiez si le paramètre --host est défini sur l'adresse IP du pont Docker ou l'adresse IP interne de l'hôte, afin que le conteneur Docker puisse accéder au service.

2. Vérifiez si le groupe de sécurité du serveur cloud ou le pare-feu de l'hôte autorise le trafic TCP du conteneur Docker vers le port du proxy (par exemple, 8088).

Comment afficher les journaux d'exécution du service mcp-proxy ?

Si le proxy est configuré en tant que service systemd, exécutez la commande suivante pour afficher les journaux en temps réel :

sudo journalctl -u aliyun-mcp-proxy -f