Documentation/Developer guides
Connect an MCP client
Let an external AI use authorized device tools through MCP without implementing remote connection protocols yourself.
On this page
Prepare the endpoint and key
Open MCP management, copy the current deployment's endpoint and create a dedicated key. The transport is Streamable HTTP, the path is /mcp, and authentication uses an Authorization: Bearer header.
Use the endpoint of the deployment hosting your workspace, not a marketing page or remote device address. Read Access keys and enable only the permissions needed.
Configure your client
Add a connection in a client supporting remote HTTP MCP and Bearer authentication. Enter the endpoint and supply the key through its supported credential settings. A client that only supports local stdio cannot run an HTTP address as a local command.
MCP management also provides copyable client configuration. Its environment variable name must match the environment running your client. Restart or reconnect after changing the environment. Do not paste the key into a chat message.
Verify tool discovery
Refresh the tool list, then call devices_list and confirm it returns devices you are allowed to access. Tools are registered according to enabled key scopes; missing write tools do not necessarily indicate a connection failure.
| Task | Example tools | Permission |
|---|---|---|
| Discover devices | devices_list | devices.list |
| System information | device_info_read | device.read |
| View a screen | desktop_open, desktop_snapshot | desktop.view |
| Control a screen | desktop_action | desktop.control |
| Read files | files_open, files_read_text | files.read |
| Change files | files_write_text | files.write |
| Remote terminal | terminal_open, terminal_write | terminal.open |
Use the discovered tool schema for exact parameters. Capabilities that are not enabled globally cannot be activated by selecting key permissions.
Use remote sessions in order
For a desktop, call desktop_open, then desktop_snapshot to obtain the current screen. Coordinate actions require its latest frame_id and use the returned image's pixel coordinates. If a stale frame is rejected, take a new snapshot instead of retrying old coordinates.
Read existing file content before changing it and send expected_sha256 when overwriting. A single text or binary body is limited to 1 MiB. Terminal input, file changes and desktop control change target state and must follow the host client's approval rules.
Call session_close when finished. Remote sessions expire within 10 minutes; open a new session afterward instead of reusing a closed session or another client's ID.
Diagnose connection failures
For authentication errors, check the endpoint, key expiry and revocation. If connected but no devices appear, check group access. If devices appear but operations fail, check the specific scope, online state and target capability.
For custom programs, continue to API and code examples. For general problems, see Troubleshooting.
Include the issue and the steps you took so it is easier to investigate.