AgentBay:MCP Tools Overview

Tool capability

Tool name

Tool description

Parameter example

Create sandbox environment

create_sandbox

Creates a new AgentBay sandbox and returns its ID.

{
  "type": "object",
  "properties": {},
  "required": []
}

Get sandbox access URL

get_sandbox_url

Get the Wuying MCP runtime URL for user access. Each URL is valid for a single use and expires immediately.

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

Take full-screen screenshot and share

system_screenshot

Captures a full-screen screenshot of the current screen and returns a shareable URL. The screenshot is automatically processed and stored securely. For security, the generated URL expires after 64 minutes.

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

Release sandbox resources

kill_sandbox

Releases resources after the task is complete.

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

Run shell command

shell

Runs a shell command and returns the output or an error.

{
  "inputSchema": {
    "properties": {
      "command": {
        "description": "The command entered by the client.",
        "type": "string"
      },
      "timeout_ms": {
        "default": 1000,
        "description": "The command execution timeout in milliseconds. If not specified, a default value (for example, 1000 ms) is used.",
        "type": "integer"
      }
    },
    "required": ["command", "timeout_ms"],
    "type": "object"
  }
}

Close browser page

browser_close

Closes the browser page.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Resize browser window

browser_resize

Resizes the browser window.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "width": {
        "type": "number",
        "description": "The width of the browser window."
      },
      "height": {
        "type": "number",
        "description": "The height of the browser window."
      }
    },
    "required": ["width", "height"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Get console messages

browser_console_messages

Returns all console messages.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Handle pop-up dialog

browser_handle_dialog

Handles a dialog box.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "accept": {
        "type": "boolean",
        "description": "Whether to accept the dialog box."
      },
      "promptText": {
        "type": "string",
        "description": "The prompt text in a prompt dialog box."
      }
    },
    "required": ["accept"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Upload file in browser

browser_file_upload

Uploads one or more files.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "paths": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "The absolute paths of the files to upload. Can be a single file or multiple files."
      }
    },
    "required": ["paths"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Install browser

browser_install

Installs the browser specified in the configuration. Call this tool if you receive an error that the browser is not installed.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Press key in browser

browser_press_key

Presses a key on the keyboard.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "The name of the key to press or the character to generate, such as `ArrowLeft` or `a`."
      }
    },
    "required": ["key"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Navigate to URL in browser

browser_navigate

Navigates to a URL.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The URL to navigate to."
      }
    },
    "required": ["url"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Navigate back in browser

browser_navigate_back

Navigates to the previous page.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Navigate forward in browser

browser_navigate_forward

Navigates to the next page.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Get network requests

browser_network_requests

Returns all network requests since the page was loaded.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Take page screenshot

browser_take_screenshot

Takes a screenshot of the current page. You cannot perform actions based on the screenshot. Use `browser_snapshot` for actions.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "raw": {
        "type": "boolean",
        "description": "Whether to return uncompressed data in PNG format. The default is false, which returns a JPEG image."
      },
      "filename": {
        "type": "string",
        "description": "The filename to save the screenshot. If not specified, the default is `page-{timestamp}.{png|jpeg}`."
      },
      "element": {
        "type": "string",
        "description": "A human-readable description of the element to get permission for the screenshot. If not provided, the viewport is captured. If `element` is provided, `ref` must also be provided."
      },
      "ref": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot. If not provided, the viewport is captured. If `ref` is provided, `element` must also be provided."
      }
    },
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Capture page snapshot

browser_snapshot

Captures an accessibility snapshot of the current page.

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Click in browser

browser_click

Performs a click action on a web page.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "A human-readable description of the element to get permission to interact with it."
      },
      "ref": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot."
      }
    },
    "required": ["element", "ref"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Drag browser element

browser_drag

Performs a drag-and-drop operation between two elements.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "startElement": {
        "type": "string",
        "description": "A human-readable description of the source element to get permission to interact with it."
      },
      "startRef": {
        "type": "string",
        "description": "A reference to the source element in the page snapshot."
      },
      "endElement": {
        "type": "string",
        "description": "A human-readable description of the target element to get permission to interact with it."
      },
      "endRef": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot."
      }
    },
    "required": ["startElement", "startRef", "endElement", "endRef"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Hover over browser element

browser_hover

Hovers the mouse over a page element.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "A human-readable description of the element to get permission to interact with it."
      },
      "ref": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot."
      }
    },
    "required": ["element", "ref"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Type text in browser

browser_type

Types text into an editable element.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "A human-readable description of the element to get permission to interact with it."
      },
      "ref": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot."
      },
      "text": {
        "type": "string",
        "description": "The text to type into the element."
      },
      "submit": {
        "type": "boolean",
        "description": "Whether to submit the entered text (press Enter after typing)."
      },
      "slowly": {
        "type": "boolean",
        "description": "Whether to type character by character. This is useful for triggering key press handlers on the page. By default, the entire text is filled at once."
      }
    },
    "required": ["element", "ref", "text"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Select option from dropdown

browser_select_option

Selects an option in a dropdown menu.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "A human-readable description of the element to get permission to interact with it."
      },
      "ref": {
        "type": "string",
        "description": "A reference to the target element in the page snapshot."
      },
      "values": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "An array of values to select in the dropdown menu. Can be a single value or multiple values."
      }
    },
    "required": ["element", "ref", "values"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Wait for page content

browser_wait_for

Waits for text to appear or disappear, or for a specified time to pass.

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "time": {
        "type": "number",
        "description": "The time to wait in seconds."
      },
      "text": {
        "type": "string",
        "description": "The text to wait for."
      },
      "textGone": {
        "type": "string",
        "description": "The text to wait for to disappear."
      }
    },
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

Create directory

create_directory

Creates a new directory or ensures a directory exists. You can create multiple nested directories in a single operation. If the directory already exists, this operation succeeds silently. Ideal for setting up the required directory structure for a project or ensuring a required path exists. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "The path of the directory to create.",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

Edit file by line

edit_file

Performs line-based edits on a text file. Each edit replaces an exact sequence of lines with new content. Returns a git-style diff to show the changes made. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "dryRun": {
        "default": false,
        "description": "Preview changes using git-style diff format.",
        "type": "boolean"
      },
      "edits": {
        "items": {
          "properties": {
            "newText": {
              "description": "The new text to replace with.",
              "type": "string"
            },
            "oldText": {
              "description": "The text to search for - must be an exact match.",
              "type": "string"
            }
          },
          "required": ["oldText", "newText"],
          "type": "object"
        },
        "type": "array"
      },
      "path": {
        "description": "The path of the file to edit.",
        "type": "string"
      }
    },
    "required": ["path", "edits"],
    "type": "object"
  }
}

Get file metadata

get_file_info

Retrieves detailed metadata for a file or directory. Returns comprehensive information including size, creation time, last modification time, permissions, and type. This tool is ideal for understanding file characteristics without reading the actual content. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "The path of the file or directory to inspect.",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

Read file content

read_file

Reads the content of a file from the filesystem. You can specify an optional 'offset' (in bytes) to start reading from a specific position, and an optional 'length' (in bytes) to limit the number of bytes to read. If 'length' is omitted or is 0, the file is read to the end. Handles various text encodings and provides detailed error messages if the file cannot be read. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "length": {
        "description": "The number of bytes to read. If omitted or 0, reads to the end of the file.",
        "minimum": 0,
        "type": "integer"
      },
      "offset": {
        "default": 0,
        "description": "Start reading from this byte offset.",
        "minimum": 0,
        "type": "integer"
      },
      "path": {
        "description": "The path of the file to read.",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

Read multiple files

read_multiple_files

Reads the content of multiple files simultaneously. This is more efficient than reading files one by one when you need to analyze or compare multiple files. The content of each file is returned with its path as a reference. A failure to read a single file does not stop the entire operation. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "paths": {
        "description": "An array of file paths to read.",
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": ["paths"],
    "type": "object"
  }
}

List directory files

list_directory

Gets a detailed list of all files and directories in a specified path. The results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is useful for understanding directory structure and finding specific files. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "The path of the directory to list.",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

Move or rename file

move_file

Moves or renames files and directories. You can move a file to a different directory and rename it in a single operation. The operation fails if the destination already exists. It can work between different directories and can be used for simple renames within the same directory. Both source and destination must be in allowed directories.

{
  "inputSchema": {
    "properties": {
      "destination": {
        "description": "The destination file or directory path.",
        "type": "string"
      },
      "source": {
        "description": "The source file or directory path.",
        "type": "string"
      }
    },
    "required": ["source", "destination"],
    "type": "object"
  }
}

Search files recursively

search_files

Recursively searches for files and directories that match a pattern. Searches all subdirectories from the starting path. The search is case-sensitive and matches partial names. Returns the full path of all matching items. Ideal for finding files when you do not know the exact location. Searches only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "excludePatterns": {
        "default": [],
        "description": "Patterns to exclude (optional).",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "path": {
        "description": "The directory path to start the search from.",
        "type": "string"
      },
      "pattern": {
        "description": "The pattern to match.",
        "type": "string"
      }
    },
    "required": ["path", "pattern"],
    "type": "object"
  }
}

Write file content

write_file

Creates a new file or writes to the content of an existing file. You can choose to completely overwrite the file or append to the end of the file by specifying the mode parameter. Use overwrite mode (default) to clear the file before writing, or use append mode to add content to the end of the file. Handles text content with appropriate encoding. Works only in allowed directories.

{
  "inputSchema": {
    "properties": {
      "content": {
        "description": "The content to write.",
        "type": "string"
      },
      "mode": {
        "default": "overwrite",
        "description": "Write mode: 'overwrite' clears the file, 'append' adds to the end of the file.",
        "enum": ["overwrite", "append"],
        "type": "string"
      },
      "path": {
        "description": "The path of the file to write to.",
        "type": "string"
      }
    },
    "required": ["path", "content"],
    "type": "object"
  }
}

Synchronously execute page operation

page_use_act

Executes one or more actions on the current webpage and blocks until all actions are complete.

This method immediately executes the provided actions through the current agent and returns the final result after the entire sequence of actions is complete. It can handle single interactions along with a series of consecutive actions.

{
  "type": "object",
  "title": "page_use_actArguments",
  "required": [
    "sandbox_id",
    "action"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "variables": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object",
      "title": "Variables"
    },
    "action": {
      "type": "string",
      "title": "Action"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "type": "boolean",
      "title": "Iframe"
    },
    "timeout_ms": {
      "type": "integer",
      "title": "Timeout Ms"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

Take webpage screenshot

page_use_screenshot

Captures a screenshot of the current webpage.

This tool provides flexible screenshot capabilities, supporting full-page screenshots, cropping of specified areas, and image quality settings. The result is returned as a data URL (such as data:image/png;base64), which can be used directly in frontend applications.

{
  "type": "object",
  "title": "page_use_screenshotArguments",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "full_page": {
      "default": true,
      "type": "boolean",
      "title": "Full Page"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "clip": {
      "additionalProperties": {
        "type": "number"
      },
      "type": "object",
      "title": "Clip"
    },
    "timeout": {
      "type": "integer",
      "title": "Timeout"
    },
    "quality": {
      "default": 80,
      "type": "integer",
      "title": "Quality"
    }
  },
  "required": [
    "sandbox_id"
  ]
}

Close browser session

page_use_close_session

Closes the current browser proxy session.

This terminates the browser process managed by the proxy and releases related resources.

{
  "type": "object",
  "title": "page_use_close_sessionArguments",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

Find interactive elements

page_use_observe

Identifies and locates interactive user interface elements.

This tool helps you discover and describe elements that can be interacted with (such as buttons or input fields) for use in subsequent actions.

Use the observe tool when you need to find actionable elements.

To extract structured data or text content, use the extract tool instead.

{
  "type": "object",
  "title": "page_use_observeArguments",
  "required": [
    "sandbox_id",
    "instruction"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "instruction": {
      "type": "string",
      "title": "Instruction"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "default": false,
      "type": "boolean",
      "title": "Iframe"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

Asynchronously execute page operation

page_use_act_async

Asynchronously starts executing one or more actions on the current webpage and returns a task_id for progress polling.

Unlike page_use_act, this method does not block until the actions are complete. It starts execution immediately, returns a unique task_id, and allows the client to poll for intermediate progress and the final result using page_use_get_act_result.

{
  "type": "object",
  "title": "page_use_act_asyncArguments",
  "required": [
    "sandbox_id",
    "action"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "variables": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object",
      "title": "Variables"
    },
    "action": {
      "type": "string",
      "title": "Action"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "type": "boolean",
      "title": "Iframe"
    },
    "timeout_ms": {
      "type": "integer",
      "title": "Timeout Ms"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

Get asynchronous operation task progress

page_use_get_act_result

Gets the current progress or final result of an asynchronous operation task.

This method should be used with the task_id obtained from a previous call to page_use_act_async. It returns the current status of the task and, if the execution is complete (is_done), includes the corresponding result content.

{
  "type": "object",
  "title": "page_use_get_act_resultArguments",
  "required": [
    "sandbox_id",
    "task_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  }
}

Get asynchronous extraction task result

page_use_get_extract_result

Asynchronous function to get the result of an extract task.

{
  "type": "object",
  "title": "page_use_get_extract_resultArguments",
  "required": [
    "sandbox_id",
    "task_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  }
}

Navigate to URL on page

page_use_navigate

Navigates to the specified URL in the browser.

{
  "type": "object",
  "title": "page_use_navigateArguments",
  "required": [
    "sandbox_id",
    "url"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "url": {
      "type": "string",
      "title": "Url"
    }
  }
}

Run code

run_code

Runs code in the specified context on the Linux platform and returns the output or an error.

{
  "inputSchema": {
    "properties": {
      "code": {
        "description": "The code to run.",
        "type": "string"
      },
      "language": {
        "description": "The programming language for code execution. Supported values: 'python', 'javascript'. If not specified, Python is used by default.",
        "type": "string"
      },
      "timeout_s": {
        "default": 300,
        "description": "Command execution timeout in seconds. If not specified, the default is 300 seconds, with a maximum of 3600 seconds.",
        "type": "integer"
      }
    },
    "required": ["code"],
    "type": "object"
  }
}