Alibaba Cloud CLI:Proxy an OpenAPI MCP server with aliyun mcp-proxy

Step 1: Configure the Alibaba Cloud CLI

1. Install or upgrade the Alibaba Cloud CLI to version 3.2.0 or later. For installation instructions, see Install the CLI (Linux).

2. Configure the CLI with the credentials of an Alibaba Cloud account or a RAM user that has permissions to create OAuth applications. Alternatively, you can use the --oauth-app-name parameter in subsequent steps to specify an existing OAuth application.

   aliyun configure
   # Enter your AccessKey ID, AccessKey Secret, and default region as prompted.

Step 2: Initial run and OAuth authorization

When you run mcp-proxy for the first time, you must complete a one-time OAuth authorization to obtain permission to refresh the token.

1. Start the proxy in the foreground.

   • In an environment with a graphical user interface, when the --no-browser parameter is not used, the CLI automatically launches a browser to perform the OAuth authorization flow. After the authorization is complete, you do not need to manually enter the code. You can then skip to Step 5.

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

   • When you operate in a server environment without a graphical user interface, add the --no-browser parameter. You will then be guided to obtain a code.

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

   Note

   You can use the --oauth-app-name parameter to specify a custom OAuth application that must meet the following conditions:

   • OAuth scope: Must be /acs/mcp-server.

   • Redirect URI: Must be the same as the redirect URI used for aliyun mcp-proxy authentication.

   • Application Type: Must be a Native application.

     

2. The terminal displays the authorization URL.

   Setting up MCPOAuth profile 'default-mcp'...
   Opening browser for OAuth login...
   URL: https://signin.aliyun.com/oauth2/v1/auth?client_id=XXX8&response_type=code&scope=%2Facs%2Fmcp-server&redirect_uri=http://0.0.0.0: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. Open the URL in a browser, log in, and complete the authorization.

4. After successful authorization, the page redirects to a URL that contains the code parameter or directly displays the authorization code. Copy the code value and paste it into the terminal, and then press the Enter key to confirm.

5. When the terminal displays the OAuth login successful! message, the authorization login is successful.

   2025/12/04 19:11:49 Oauth authorization successfully, code received: XXXX
   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. When the terminal displays the MCP Proxy Server Started message, it indicates that the proxy has started successfully.

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

Step 3: Configure as a systemd service

To ensure the proxy runs continuously, configure it as a systemd service that starts on boot.

1. Create a systemd service file: aliyun-mcp-proxy.

   Note:

   • Replace your-user in the command with the username of the non-root user that you use to run this command. This user must have configured credentials by using aliyun configure.

   • The $(which aliyun) command in ExecStart automatically locates the path to the aliyun command. If this process fails, you can manually replace it with the output of the which aliyun command, for example, /usr/local/bin/aliyun.

   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=$(which aliyun) 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. Reload the systemd configuration and start the 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

Step 4: Verify the proxy service

Verify that the service is running correctly by using one of the following methods.

• View the service status

  Run the following command to view the service status.

  sudo systemctl status aliyun-mcp-proxy

  If the output contains active (running), the service has started successfully.

• Request the proxy port

  Run the following command to send a request directly to the proxy port.

  curl http://127.0.0.1:8088/

  If the proxy is working correctly, you will receive an XML-formatted error response from the MCP server. This response confirms the connection between the proxy and the server.

  <?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.aliyun.com/troubleshoot?q=InvalidAction.NotFound&product=OpenAPIExplorer&requestId=B3311876-XXX]]></Recommend></Error>

Step 1: Get host IP and start mcp-proxy

The Dify container needs to access the mcp-proxy service through the Docker bridge IP address of the host.

1. Run the following command to get and record the IP address.

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

   An IP address similar to 172.17.0.1 is returned.

2. Start the aliyun mcp-proxy proxy service in the foreground. Alternatively, modify the startup command in systemd and then start it as a service.

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

Step 2: Configure MCP server in Dify

1. Go to the Tools > MCP configuration page in Dify.

2. Click Add MCP Server (HTTP).

3. In the Server URL field, enter your MCP proxy address.

   You can obtain the original Streamable HTTP Endpoint address from the Alibaba Cloud OpenAPI MCP Server console. Replace the hostname of this address with your local or internal network proxy address.

   Example conversion:

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

   • Replace with the proxy address (assuming the proxy is running on 172.17.0.1:8088):
     http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp
     
     

4. Enter other information as needed, and click Add & Authorize. Dify will communicate with your MCP service through this proxy address.

Mitigation measures

• Environment isolation: Run the proxy only in a trusted, single-user environment. Avoid using it on multi-user shared servers.

• Network access control: Bind the proxy listening address (--host) to 127.0.0.1 (the default) or a specific internal IP address. Use firewall or security group rules to restrict access to the proxy port. For example, allow access only from specific application server IPs. Do not expose the port to the public internet.

• Access control: Use the --allowed-servers or --blocked-servers parameter to restrict which MCP Servers can be accessed and prevent the proxy from being used to access unintended services. For more information, see Configure server access control.

• Principle of least privilege: Configure the minimum necessary permissions for the CLI user that the proxy uses and its associated MCP server. Grant read-only permissions whenever possible.

• Auditing and monitoring: Regularly review the proxy service's access logs and monitor for unusual requests. Requests blocked by access control are recorded in the proxy logs.

Configure server access control

aliyun mcp-proxy supports whitelist and blacklist mechanisms to restrict the range of MCP Servers that can be accessed through the 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

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

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

Available Servers:
  - ecs
    MCP: http://127.0.0.1:8088/acs/mcp-server/ecs/mcp
  - oss
    MCP: http://127.0.0.1:8088/acs/mcp-server/oss/mcp
  - ram (blocked)

Security incident response

If you suspect that the proxy's authentication token has been leaked or abused, take these immediate actions:

• Stop the mcp-proxy service.

• Delete the local configuration file: rm ~/.aliyun/.mcpproxy_config.

• Revoke the OAuth authorization in the Alibaba Cloud console.

• Check API call logs to identify any unauthorized operations.

• Reconfigure the mcp-proxy and generate a new token.

Why do I get an "ERROR: OAuth flow returned empty RefreshToken" error when running aliyun mcp-proxy?

This error usually occurs if the OAuth application is misconfigured or if you are using an unsupported authentication method. Ensure that:

• The OAuth application type is set to Native.

• Authentication must be done with a primary account or a RAM user. Assuming a RAM role is not supported for obtaining an OAuth refresh token.

Why do I get a "Connection Refused" or "Timeout" error after configuring the proxy in Dify?

Check the following:

1. When the mcp-proxy service starts, has the --host parameter been set to the Docker bridge IP or the host's internal IP address to ensure that Docker containers can access it?

2. Whether the cloud server security group or the host firewall allows TCP traffic from the Docker container to the proxy port (such as 8088).

How do I view mcp-proxy service logs?

If it is configured as a systemd service, you can use the following command to view the logs in real time:

sudo journalctl -u aliyun-mcp-proxy -f