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

Step 1: Configure Alibaba Cloud CLI

1. Install or upgrade Alibaba Cloud CLI to version 3.5.0 or later. For instructions, see Install, update, and uninstall Alibaba Cloud CLI.

2. Configure the CLI with the AccessKey pair of an Alibaba Cloud account or a RAM user.

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

   If you use a RAM user, grant the permissions in the following table to the RAM user.

   Permission	Purpose	Scenarios
   ram:ListApplications	Queries OAuth applications by name.	Required. The proxy needs this permission on the first start, or when the locally saved authorization information is unavailable. This permission is also required when you use --oauth-app-name to specify an existing application.
   ram:CreateApplication	Creates the default OAuth application aliyun-cli-mcp-proxy.	Required when you do not use --oauth-app-name to specify an application and the default application does not exist.
   ram:GetApplication	Queries OAuth applications by ID.	Recommended. The proxy uses this permission to reuse the locally saved authorization information. Without this permission, the proxy must complete a new OAuth authorization on every start.

Step 2: Run the proxy for the first time and complete OAuth authorization

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

1. Start the proxy in the foreground.

   • In an environment with a GUI, if you do not add the --no-browser parameter, the CLI automatically opens a browser to run the OAuth authorization sign-in flow, and you do not need to enter the authorization code manually. After the authorization is complete, skip to step 5.

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

   • On a server without a GUI, add the --no-browser parameter. The following steps guide you to obtain the authorization code manually.

     aliyun utils 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. The application must meet the following requirements:

   • OAuth scope: Includes the authorization scope specified by the --scope parameter. The default value is /acs/mcp-server.

   • Redirect URI: Includes http://<host>:<port>/callback, where host and port are the values of the --host and --port parameters that you use to start the proxy.

   • Application type: Must be a NativeApp application.

2. The terminal prints the authorization URL.

   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. Open the URL in a browser, sign in, and complete the authorization.

4. After the authorization succeeds, the page redirects to an address that contains the code parameter, or directly displays the authorization code. Copy the code value, paste it into the terminal, and press Enter to confirm.

5. When the terminal displays the OAuth login successful! message, the authorization sign-in succeeds.

   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. When the terminal displays the MCP Proxy Server Started message, the proxy starts successfully.

   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

Step 3: Configure a systemd background service (CentOS example)

To keep the proxy running stably, configure it as a systemd service that starts on boot.

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

   Replace the following content:

   • Replace your-user in the command with the actual non-root username that runs this command. This user must have configured credentials by running aliyun configure, and must have completed the preceding OAuth authorization under this user. When the service starts, it reuses the authorization credentials saved in the home directory of this user and does not trigger browser authorization again.

   • ExecStart must contain the absolute path of the aliyun command. Run which aliyun to get the actual path, and replace /usr/local/bin/aliyun in the example. systemd does not parse this field through a shell, so command substitution such as $(which aliyun) does not take effect.

   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. 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 runs properly by using either 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 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 works properly, you receive an XML error response from the MCP server, which indicates that the connection between the proxy and the service is established.

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

Step 1: Get the Docker bridge IP address of the host and start the mcp-proxy service

The Dify container must 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

   The command returns an IP address such as 172.17.0.1.

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

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

   Note

   The callback address is determined by both the --host and --port parameters. After you change the listen address from 127.0.0.1 to the Docker bridge IP address, add the new callback address (for example, http://172.17.0.1:8088/callback) to the corresponding OAuth application under Integrations > OAuth Applications (Public Preview) in the RAM console. Otherwise, the startup fails because the callback address does not pass validation.

Step 2: Configure the MCP server in Dify

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

2. Click Add MCP Server (HTTP).

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

   In the Alibaba Cloud OpenAPI MCP Service console, get the original Streamable HTTP Endpoint address, and replace the domain part (host) of the address with your local or internal 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 (assume that the proxy runs on 172.17.0.1:8088): http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. Fill in the other information as needed and click Add & Authorize. Dify communicates with the MCP service through this proxy address.

Mitigations

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

• Network access control — Bind the proxy listen address (--host) to 127.0.0.1 (default) or a specific internal IP address. Use firewall or security group rules to limit the access scope of the proxy port (for example, allow access only from specific application server IP addresses), and never expose the port to the Internet.

• Access control — Use the --allowed-servers or --blocked-servers parameter to limit the scope of accessible MCP servers and prevent the proxy from being used to access unintended services. For instructions, see Configure server access control.

• Principle of least privilege — Configure least privilege access for the CLI user that the proxy uses and the associated MCP servers. Grant read-only permissions first.

• Auditing and monitoring — Review the access logs of the proxy service regularly and monitor abnormal requests. Requests blocked by access control are recorded in the proxy logs.

Configure server access control

aliyun utils mcp-proxy supports whitelist and blacklist mechanisms to limit the scope 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

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

Security incident response

If you suspect that the proxy authentication token is leaked or abused, immediately perform the following operations:

• Stop the mcp-proxy service.

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

• Delete the OAuth application to permanently invalidate the leaked refresh token. Log on to the RAM console as a RAM administrator. In the left-side navigation pane, choose Integrations > OAuth Applications (Public Preview). On the Enterprise Applications tab, click Delete Application in the Actions column of the target application. You can also use the CLI to delete the application. After the deletion, when you complete OAuth authorization again, the CLI automatically creates a new application.

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

• Check the API call logs to confirm whether abnormal operations exist.

• Restart the proxy and complete OAuth authorization to obtain a new token.

After you run aliyun utils mcp-proxy for OAuth authentication, the “ERROR: OAuth flow returned empty RefreshToken” error appears and the proxy fails to start. Why?

This error indicates that the OAuth application currently in use is not a NativeApp application, so it cannot return a refresh token in the authorization flow. Handle the issue in either of the following ways:

• Delete the OAuth application and then restart the proxy. The CLI automatically creates a NativeApp application.

• Manually create a NativeApp application, and specify the application by using --oauth-app-name when you start the proxy.

What do I do if the failed to find OAuth application error appears with the NoPermission error code when I start the proxy?

Error example:

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

During the startup stage, the proxy needs to query or create an OAuth application, and this operation is completed by using the Alibaba Cloud CLI credentials. The preceding error indicates that the RAM user corresponding to the current CLI credentials has not been granted the permission specified by the AuthAction field (ram:ListApplications in this example).

Handle the issue in either of the following ways:

• Grant the required permissions to the RAM user. For more information, see Step 1: Configure Alibaba Cloud CLI.

• Run the proxy by using credentials that have the required permissions, such as an Alibaba Cloud account or another RAM user that has completed authorization.

What do I do if the startup fails with the does not have required redirect URI error after I change --host or --port?

The OAuth application must contain the callback address that corresponds to the current startup. Changing --host or --port changes this address. Error example:

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]

Log on to the RAM console as a RAM administrator. In the left-side navigation pane, choose Integrations > OAuth Applications (Public Preview). On the Enterprise Applications tab, click the name of the target application. In the Basic Information section, click Edit, and add the address indicated by required redirect URI in the error message to the callback addresses. The same application can keep multiple callback addresses, and the existing addresses remain available after you add a new one.

What do I do if “Connection Refused” or “Timeout” appears after I configure the proxy in Dify?

Check the following two items:

1. When the mcp-proxy service starts, check whether the --host parameter is set to the Docker bridge IP address or the internal IP address of the host, so that the Docker container can access the service.

2. Check whether the security group of the cloud server or the firewall of the host allows TCP traffic from the Docker container to the proxy port (for example, 8088).

How do I view the running logs of the mcp-proxy service?

If the proxy is configured as a systemd service, run the following command to view the logs in real time:

sudo journalctl -u aliyun-mcp-proxy -f