MCP integration guide - AgentBay - Alibaba Cloud Documentation Center

The AgentBay platform provides a unified interaction interface between AI models and their running environments based on the open standard Model Context Protocol (MCP). Because the platform is deeply integrated with the cloud environment, developers can use MCP to directly access cloud features such as session management, file operations, command execution, application management, and window control.

Prerequisites

You must have an API key to complete this procedure. For more information, see Create an API key.

Procedure

Step 1: Set an image

Specify an image in the IMAGEID field of the MCP address. The following MCP addresses are examples. You must use the actual code from your console. For more information about how to obtain the MCP address, see Get an MCP address.

Set the latest image

Refer to one of the following examples based on your environment. If you set the image to latest, the system always uses the latest image for that environment.

Windows

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=windows_latest"
    }
  }
}

Linux

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=linux_latest"
    }
  }
}

Browser

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=browser_latest"
    }
  }
}

Code

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=code_latest"
    }
  }
}

Mobile

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=mobile_latest"
    }
  }
}

Set a specific image ID

You can also set the IMAGEID field to the ID of an OS image or a custom image. The system will then use the image that corresponds to that ID.

Set a specific OS image

Note

To obtain the image ID:

Log on to the AgentBay console and click Image Management (Beta). On the Images (Beta) page, click the System Image tab. Find the ID of your target image in the list and use it to replace <YOUR_IMAGEID> in the following command.

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=<YOUR_IMAGEID>"
    }
  }
}

Set a specific custom image

Note

To obtain the image ID:

Log on to the AgentBay console and click Image Management (Beta). On the Images (Beta) page, click the Custom Image tab. Find the ID of your target image in the list and use it to replace <YOUR_IMAGEID> in the following command.

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay.wuying.aliyuncs.com/v2/sse?APIKEY=akm-**************&IMAGEID=<YOUR_IMAGEID>"
    }
  }
}

Step 2: Configure the MCP service

Copy the MCP address code block to a tool that supports MCP, such as Cline or Cursor. The following steps use Cursor V0.50.5 as an example.

Open the Cursor Settings panel and click MCP in the left navigation pane.
On the MCP Servers panel, click Add new global MCP server in the upper-right corner.

In the mcp.json file, paste the MCP address code block that you copied as described in Get an MCP address. Save the file to complete the configuration.

SSE, Stdio, and Streamable connection methods are supported. Choose a method that suits your project.

SSE

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay-intl.wuying.aliyuncs.com/v2/sse?APIKEY=YOUR_API_KEY&IMAGEID=linux_latest"
    }
  }
}

Streamable

{
  "mcpServers": {
    "wuying_mcp_server": {
      "url": "https://agentbay-intl.wuying.aliyuncs.com/v2/mcp?APIKEY=YOUR_API_KEY&IMAGEID=linux_latest"
    }
  }
}

Step 3 (Optional): Use the display stream feature

If the resource type is a General Resource Pool or an Independent Resource Pool, the cloud computer display can be opened in two ways, by embedding it in an iframe using the Alibaba Cloud Workspace Web SDK or by launching the Alibaba Cloud Workspace Web Client directly in a browser. When you request the cloud computer display stream, MCP will return a URL containing the necessary authentication parameters. The URL will be in the following format: https://wuying.aliyun.com?mcp.html?authcode=<authCode>&resourceId=<resourceId>

Important

The authcode and resourceId are important logon credentials returned via MCP. Do not modify them.

The link has an expiration time and can only be used a limited number of times. Use the link immediately after you receive it.
You can enable or disable keyboard and mouse interaction using the &input=true&keyboard=true parameters in the URL. You can also configure this setting in real time using the Web SDK API. For more information, see the Web SDK documentation.

MCP tools

The following table describes MCP tools and their applicable scope.

Class	Description	Environment (Image)
Class	Description	Computer Use Windows	Computer use Linux	Browser Use	Mobile use	CodeSpace
Sessions	The Session class represents a session in the AgentBay cloud environment. It provides methods to manage the file system and execute commands.	Support	Support	Support	Support	Support
FileSystem	The FileSystem class provides methods for file operations in an AgentBay cloud environment session. These operations include reading, writing, editing, and searching for files, and managing folders.	Support	Support	Support	Not support	Support
OSS	The Object Storage Service (OSS) provides features to interact with the cloud storage service.	Support	Support	Not support	Support	Support
UI	The UI class provides methods to interact with UI elements in the AgentBay cloud environment. These methods include getting UI elements, sending key events, entering text, performing gestures, and taking screenshots.	Support	Support	Not support	Support	Not applicable
Application	The Application class provides methods to manage applications in the AgentBay cloud environment. These methods include listing installed applications, starting applications, and stopping running processes.	Support	Not support	Not support	Not support	Not applicable
Context	The Context API provides features to manage persistent storage contexts in the AgentBay cloud environment. Contexts let you persist data between sessions and reuse it in future sessions.	Not applicable	Not applicable	Not applicable	Not applicable	Not applicable
Command	The Command class provides methods to execute commands in an AgentBay cloud environment session.	Support	Support	Support	Support	Support
CodeSpace	Executes code in a specified programming language and sets a timeout.	Not applicable	Not applicable	Not applicable	Not applicable	Support