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

Etapa 1: Configurar o Alibaba Cloud CLI

1. Instale ou atualize o Alibaba Cloud CLI para a versão 3.5.0 ou posterior. Para obter instruções, consulte Install, update, and uninstall Alibaba Cloud CLI.

2. Configure o CLI com o par de AccessKey de uma conta do Alibaba Cloud ou de um usuário do RAM.

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

   Caso utilize um usuário do RAM, conceda a ele as permissões listadas na tabela a seguir.

   Permissão	Finalidade	Cenários
   ram:ListApplications	Consulta aplicativos OAuth por nome.	Obrigatório. O proxy precisa dessa permissão na primeira execução ou quando as informações de autorização salvas localmente não estão disponíveis. Essa permissão também é necessária ao usar --oauth-app-name para especificar um aplicativo existente.
   ram:CreateApplication	Cria o aplicativo OAuth padrão aliyun-cli-mcp-proxy.	Obrigatório caso o parâmetro --oauth-app-name não seja usado para especificar um aplicativo e o aplicativo padrão não exista.
   ram:GetApplication	Consulta aplicativos OAuth por ID.	Recomendado. O proxy usa essa permissão para reutilizar as informações de autorização salvas localmente. Sem essa permissão, será necessário concluir uma nova autorização OAuth a cada inicialização.

Etapa 2: Executar o proxy pela primeira vez e concluir a autorização OAuth

Ao executar o mcp-proxy pela primeira vez, conclua a autorização OAuth única para obter a permissão de renovação de tokens.

1. Inicie o proxy em primeiro plano.

   • Em um ambiente com interface gráfica, caso não adicione o parâmetro --no-browser, o CLI abrirá automaticamente um navegador para executar o fluxo de login da autorização OAuth, eliminando a necessidade de inserir o código de autorização manualmente. Após concluir a autorização, pule para a etapa 5.

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

   • Em um servidor sem interface gráfica, adicione o parâmetro --no-browser. As etapas a seguir descrevem como obter o código de autorização manualmente.

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

   Nota

   Use o parâmetro --oauth-app-name para especificar um aplicativo OAuth personalizado. O aplicativo deve atender aos seguintes requisitos:

   • Escopo OAuth: Inclui o escopo de autorização especificado pelo parâmetro --scope. O valor padrão é /acs/mcp-server.

   • URI de redirecionamento: Inclui http://<host>:<port>/callback, onde host e port são os valores dos parâmetros --host e --port usados para iniciar o proxy.

   • Tipo de aplicativo: Deve ser um aplicativo NativeApp.

2. O terminal exibirá a URL de autorização.

   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. Abra a URL em um navegador, faça login e conclua a autorização.

4. Após a autorização ser bem-sucedida, a página redirecionará para um endereço contendo o parâmetro code ou exibirá diretamente o código de autorização. Copie o valor de code, cole-o no terminal e pressione Enter para confirmar.

5. Quando o terminal exibir a mensagem OAuth login successful!, a autenticação OAuth terá sido concluída com sucesso.

   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. Quando o terminal exibir a mensagem MCP Proxy Server Started, o proxy terá sido iniciado com sucesso.

   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

Etapa 3: Configurar um serviço em segundo plano do systemd (exemplo no CentOS)

Para manter o proxy em execução de forma estável, configure-o como um serviço do systemd com início automático na inicialização do sistema.

1. Crie o arquivo de serviço do systemd: aliyun-mcp-proxy.

   Substitua os seguintes valores:

   • Substitua your-user no comando pelo nome de usuário real (diferente de root) que executará este comando. Esse usuário deve ter configurado as credenciais ao executar aliyun configure e concluído a autorização OAuth anterior sob este mesmo usuário. Quando o serviço for iniciado, ele reutilizará as credenciais de autorização salvas no diretório home desse usuário, sem acionar a autorização pelo navegador novamente.

   • O ExecStart deve conter o caminho absoluto do comando aliyun. Execute which aliyun para obter o caminho real e substitua /usr/local/bin/aliyun no exemplo. O systemd não analisa esse campo por meio de um shell; portanto, substituições de comando como $(which aliyun) não surtem efeito.

   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. Recarregue a configuração do systemd e inicie o serviço.

   # 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

Etapa 4: Verificar o serviço de proxy

Verifique se o serviço está em execução adequada usando um dos métodos a seguir.

• Visualizar o status do serviço

  Execute o comando a seguir para visualizar o status do serviço.

  sudo systemctl status aliyun-mcp-proxy

  Se a saída contiver active (running), o serviço foi iniciado com sucesso.

• Fazer uma requisição para a porta do proxy

  Execute o comando a seguir para enviar uma requisição diretamente à porta do proxy.

  curl http://127.0.0.1:8088/

  Se o proxy estiver funcionando corretamente, você receberá uma resposta de erro XML do servidor MCP, indicando que a conexão entre o proxy e o serviço foi estabelecida.

  <?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>

Etapa 1: Obter o endereço IP da bridge do Docker no host e iniciar o serviço mcp-proxy

O contêiner do Dify deve acessar o serviço mcp-proxy por meio do endereço IP da bridge do Docker no host.

1. Execute o comando a seguir para obter e registrar o endereço IP.

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

   O comando retorna um endereço IP como 172.17.0.1.

2. Inicie o serviço mcp-proxy em primeiro plano. Como alternativa, modifique o comando de inicialização no systemd e inicie o serviço.

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

   Nota

   O endereço de callback é determinado pelos parâmetros --host e --port. Após alterar o endereço de escuta de 127.0.0.1 para o endereço IP da bridge do Docker, adicione o novo endereço de callback (por exemplo, http://172.17.0.1:8088/callback) ao aplicativo OAuth correspondente em Integrations > OAuth Applications (Public Preview) no console do RAM. Caso contrário, a inicialização falhará porque o endereço de callback não passará na validação.

Etapa 2: Configurar o servidor MCP no Dify

1. Acesse a página de configuração Tools > MCP no Dify.

2. Clique em Add MCP Server (HTTP).

3. No campo Server Endpoint URL, insira o endereço do proxy MCP.

   No console do OpenAPI MCP Service do Alibaba Cloud, obtenha o endereço original de Streamable HTTP Endpoint e substitua a parte do domínio (host) pelo seu endereço de proxy local ou interno.

   Exemplo de conversão:

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

   • Substitua pelo endereço do proxy (considere que o proxy esteja em execução em 172.17.0.1:8088): http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. Preencha as outras informações conforme necessário e clique em Add & Authorize. O Dify se comunica com o serviço MCP por meio desse endereço de proxy.

Mitigações

• Isolamento de ambiente — Execute o proxy apenas em um ambiente confiável de usuário único e evite usá-lo em servidores compartilhados por vários usuários.

• Controle de acesso de rede — Vincule o endereço de escuta do proxy (--host) a 127.0.0.1 (padrão) ou a um endereço IP interno específico. Use regras de firewall ou de grupo de segurança para limitar o escopo de acesso da porta do proxy (por exemplo, permita o acesso apenas de endereços IP de servidores de aplicação específicos) e nunca exponha a porta à Internet.

• Controle de acesso — Use o parâmetro --allowed-servers ou --blocked-servers para limitar o escopo de servidores MCP acessíveis e evitar que o proxy seja usado para acessar serviços não intencionais. Para obter instruções, consulte Configurar o controle de acesso ao servidor.

• Princípio do menor privilégio — Configure o acesso de menor privilégio para o usuário do CLI utilizado pelo proxy e para os servidores MCP associados. Conceda permissões de somente leitura primeiro.

• Auditoria e monitoramento — Revise os logs de acesso do serviço de proxy regularmente e monitore requisições anormais. As requisições bloqueadas pelo controle de acesso são registradas nos logs do proxy.

Configurar o controle de acesso ao servidor

O aliyun utils mcp-proxy oferece suporte a mecanismos de lista de permissões e lista de bloqueios para limitar o escopo de servidores MCP que podem ser acessados pelo 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

Resposta a incidentes de segurança

Caso suspeite que o token de autenticação do proxy vazou ou foi usado indevidamente, execute imediatamente as seguintes operações:

• Pare o serviço mcp-proxy.

• Exclua o arquivo de configuração local: rm ~/.aliyun/.mcpproxy_config.

• Exclua o aplicativo OAuth para invalidar permanentemente o token de renovação vazado. Faça login no console do RAM como administrador do RAM. No painel de navegação à esquerda, escolha Integrations > OAuth Applications (Public Preview). Na aba Enterprise Applications, clique em Delete Application na coluna Actions do aplicativo de destino. Você também pode usar o CLI para excluir o aplicativo. Após a exclusão, ao concluir a autorização OAuth novamente, o CLI criará automaticamente um novo aplicativo.

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

• Verifique os logs de chamadas de API para confirmar se existem operações anormais.

• Reinicie o proxy e conclua a autorização OAuth para obter um novo token.

Após executar o aliyun utils mcp-proxy para autenticação OAuth, o erro "ERROR: OAuth flow returned empty RefreshToken" é exibido e o proxy falha ao iniciar. Por quê?

Esse erro indica que o aplicativo OAuth em uso não é um aplicativo NativeApp e, portanto, não pode retornar um token de renovação no fluxo de autorização. Resolva o problema de uma das seguintes maneiras:

• Exclua o aplicativo OAuth e reinicie o proxy. O CLI criará automaticamente um aplicativo NativeApp.

• Crie manualmente um aplicativo NativeApp e especifique-o usando --oauth-app-name ao iniciar o proxy.

O que fazer se o erro "failed to find OAuth application" aparecer com o código de erro NoPermission ao iniciar o proxy?

Exemplo de erro:

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", ...}}

Durante a fase de inicialização, o proxy precisa consultar ou criar um aplicativo OAuth, operação concluída com as credenciais do Alibaba Cloud CLI. O erro anterior indica que o usuário do RAM correspondente às credenciais atuais do CLI não possui a permissão especificada pelo campo AuthAction (ram:ListApplications neste exemplo).

Resolva o problema de uma das seguintes maneiras:

• Conceda as permissões necessárias ao usuário do RAM. Para mais informações, consulte Etapa 1: Configurar o Alibaba Cloud CLI.

• Execute o proxy usando credenciais que tenham as permissões necessárias, como uma conta do Alibaba Cloud ou outro usuário do RAM que tenha concluído a autorização.

O que fazer se a inicialização falhar com o erro "does not have required redirect URI" após alterar --host ou --port?

O aplicativo OAuth deve conter o endereço de callback correspondente à inicialização atual. Alterar --host ou --port modifica esse endereço. Exemplo de erro:

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]

Faça login no console do RAM como administrador do RAM. No painel de navegação à esquerda, escolha Integrations > OAuth Applications (Public Preview). Na aba Enterprise Applications, clique no nome do aplicativo de destino. Na seção Basic Information, clique em Edit e adicione o endereço indicado por required redirect URI na mensagem de erro aos endereços de callback. O mesmo aplicativo pode manter vários endereços de callback, e os endereços existentes permanecerão disponíveis após a adição de um novo.

O que fazer se "Connection Refused" ou "Timeout" aparecer após configurar o proxy no Dify?

Verifique os dois itens a seguir:

1. Quando o serviço mcp-proxy for iniciado, verifique se o parâmetro --host está definido como o endereço IP da bridge do Docker ou o endereço IP interno do host, para que o contêiner do Docker possa acessar o serviço.

2. Verifique se o grupo de segurança do servidor cloud ou o firewall do host permite tráfego TCP do contêiner do Docker para a porta do proxy (por exemplo, 8088).

Como visualizar os logs de execução do serviço mcp-proxy?

Se o proxy estiver configurado como um serviço do systemd, execute o comando a seguir para visualizar os logs em tempo real:

sudo journalctl -u aliyun-mcp-proxy -f