From 86446539e8babbbf2d0b3826cc84a70da683f26c Mon Sep 17 00:00:00 2001 From: finalerock44 Date: Mon, 9 Nov 2026 16:40:40 +0000 Subject: [PATCH 1/4] docs: connect an AI agent to the hosted MCP server or dcd mcp A new page, Connect an AI Agent, sets up every client against both ways in: the hosted server (Claude Code, Cursor, VS Code, Claude Desktop, Codex and other OAuth clients), its read-only URL and API-key sign-in, and dcd mcp through the CLI, with dcd mcp install and the configs by hand. It also covers Connected apps, and points dcd-mcp users at the existing MCP Server page. --- SUMMARY.md | 1 + mcp/connect.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 mcp/connect.md diff --git a/SUMMARY.md b/SUMMARY.md index f07092a..8fd1e8f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -71,6 +71,7 @@ ## AI Agents & MCP +* [Connect an AI Agent](mcp/connect.md) * [MCP Server](mcp/overview.md) * [Tools Reference](mcp/tools.md) diff --git a/mcp/connect.md b/mcp/connect.md new file mode 100644 index 0000000..48c2381 --- /dev/null +++ b/mcp/connect.md @@ -0,0 +1,181 @@ +--- +description: "Connect Claude Code, Cursor, VS Code, Claude Desktop, Codex or another MCP client to DeviceCloud, through the hosted MCP server or the dcd CLI." +--- + +# Connect an AI Agent + +DeviceCloud's [MCP](https://modelcontextprotocol.io) server gives an AI agent such as Claude Code, Cursor, VS Code, Claude Desktop or Codex the tools to drive cloud devices and run cloud tests. You connect it in one of two ways: + +| | Install | Tools | Use it when | +| --- | --- | --- | --- | +| **Hosted**, `https://api.devicecloud.dev/mcp` | nothing | device tools | the agent drives cloud devices with apps and flows you've already uploaded | +| **`dcd mcp`**, through the CLI | the CLI | device tools and the `dcd_*` cloud-test tools | the agent also installs local builds, runs local flow files or runs cloud tests | + +::: info +The device tools are in beta, and need device sessions turned on for your organization: contact support to turn them on. If your team has them, **Settings → AI agents** in the console fills in everything on this page for you, with one-click install for Cursor and VS Code. +::: + +::: warning +We accept no liability for anything your agent may read or execute. LLMs are a new technology: use them with care and at your own risk. +::: + +## Hosted server + +The server is at `https://api.devicecloud.dev/mcp` (Streamable HTTP). The first time your client connects, it opens the DeviceCloud console in your browser: sign in, pick the organization the agent should use, and choose **Connect**. + +### Claude Code + +```bash +claude mcp add --scope user --transport http devicecloud https://api.devicecloud.dev/mcp +``` + +Then run `/mcp` in Claude Code and choose **devicecloud** to sign in. + +### Cursor + +Add the server to `~/.cursor/mcp.json`, next to any servers already in it: + +```json +{ + "mcpServers": { + "devicecloud": { "url": "https://api.devicecloud.dev/mcp" } + } +} +``` + +### VS Code + +```bash +code --add-mcp '{"name":"devicecloud","type":"http","url":"https://api.devicecloud.dev/mcp"}' +``` + +Or add it to `.vscode/mcp.json`, or to your user `mcp.json` (**MCP: Open User Configuration** in the Command Palette): + +```json +{ + "servers": { + "devicecloud": { "type": "http", "url": "https://api.devicecloud.dev/mcp" } + } +} +``` + +### Claude Desktop + +Open **Settings → Connectors** and choose **Add custom connector**. Name it DeviceCloud and paste `https://api.devicecloud.dev/mcp`. Claude Desktop's config file only takes servers that run on your machine, so the hosted server goes here. Free Claude plans allow one custom connector. + +### Codex + +```bash +codex mcp add devicecloud --url https://api.devicecloud.dev/mcp +codex mcp login devicecloud +``` + +Or add it to `~/.codex/config.toml`, then run `codex mcp login devicecloud`: + +```toml +[mcp_servers.devicecloud] +url = "https://api.devicecloud.dev/mcp" +``` + +The Codex CLI, IDE extension and ChatGPT desktop app share this file, so one setup covers all three. + +### Other clients + +Any client that supports Streamable HTTP and MCP sign-in (OAuth) can connect to `https://api.devicecloud.dev/mcp`. It finds the sign-in from the server's `401` response, registers itself, and opens the console for you to approve it. + +### Read-only + +Add `?read_only=true` to the URL for a server that offers only the tools that change nothing: `list_devices`, `get_device_status`, `inspect_screen`, `take_screenshot`, `get_command_status`, `get_logs`, `get_human_status` and `cheat_sheet`. Your agent can look at your organization's devices but can't start, drive or stop them. + +On a command line, quote the URL, because `?` is a wildcard in zsh, the default macOS shell: + +```bash +claude mcp add --scope user --transport http devicecloud 'https://api.devicecloud.dev/mcp?read_only=true' +``` + +::: warning +Read-only keeps an agent from changing anything by mistake. It isn't a permission: the same sign-in works on the URL without the flag. +::: + +### With an API key + +For an agent that can't open a browser, such as one running in CI, send an [API key](../getting-started/api-keys.md) as a header instead of signing in: + +```bash +claude mcp add --scope user --transport http devicecloud https://api.devicecloud.dev/mcp \ + --header "Authorization: Bearer " +``` + +When you create a key for an agent, choose **Device sessions only** under **Access**. That key can start and drive devices, but it can't start test runs or read their results. + +## Through the CLI: `dcd mcp` + +`dcd mcp` runs on your machine and is started by your MCP client. It passes the hosted server's device tools through, and adds what only a local process can do: `install_app` takes `app_path`, a build on your machine, and `run` takes `path`, a flow file or a directory of flows. It also serves the `dcd_*` cloud-test tools from the [Tools Reference](tools.md). + +1. Install the CLI, as in the [Quick Start](../getting-started/quickstart.md). +2. Sign in with [dcd login](../cli/dcd-login.md). +3. Add the server to your client: + +```bash +dcd mcp install claude-code # or claude-desktop, codex, cursor, vscode +``` + +Leave out the client to pick from a list. Add `--read-only` for a server that offers only the tools that change nothing, or `--print` to see what it would add without changing anything. For Claude Code, Codex and VS Code it runs their own `mcp add` command. For Claude Desktop and Cursor it adds an entry to their config file and keeps everything else in it. Restart the app afterwards. + +### Setting it up by hand + +Start dcd by its **full path**. Desktop apps are usually opened from the Dock or Start menu, so they don't see the `PATH` your shell sets up, and a bare `dcd` fails with "command not found". The installer prints the path when it finishes. It's `~/.dcd/bin/dcd` by default, written out in full, because config files don't expand `~`. + +Claude Desktop (`claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "devicecloud": { + "command": "/Users/you/.dcd/bin/dcd", + "args": ["mcp"] + } + } +} +``` + +VS Code (`.vscode/mcp.json`, or your user `mcp.json`): + +```json +{ + "servers": { + "devicecloud": { + "type": "stdio", + "command": "/Users/you/.dcd/bin/dcd", + "args": ["mcp"] + } + } +} +``` + +Codex (`~/.codex/config.toml`): + +```toml +[mcp_servers.devicecloud] +command = "/Users/you/.dcd/bin/dcd" +args = ["mcp"] +``` + +Claude Code and the Codex CLI run from a terminal, so they do see your `PATH`: + +```bash +claude mcp add --scope user devicecloud -- dcd mcp +codex mcp add devicecloud -- dcd mcp +``` + +To run the npm package instead of an installed dcd, use `npx` as the command, with the arguments `-y`, `@devicecloud.dev/dcd` and `mcp`. That needs Node 22 or later. + +`dcd mcp` signs in like the CLI: with your `dcd login` session, or with `DEVICE_CLOUD_API_KEY` set in the server's `env`. For read-only, add `--read-only` after `mcp` in the arguments, or set `DCD_MCP_READONLY=1`. + +## Connected apps + +Every client you sign in to the hosted server is listed under **Settings → Account → Connected apps**, with the organization it uses and when it was last used. **Disconnect** stops it working at once. Device sessions it starts run as you. + +## The older `dcd-mcp` server + +The npm package also has `dcd-mcp`, an older server with the `dcd_*` tools only. `dcd mcp` serves the same tools, so you only need `dcd-mcp` for a setup that already uses it. See [MCP Server](overview.md). From 850c958a476c673b1ab8e46ae0b8e10086b255df Mon Sep 17 00:00:00 2001 From: finalerock44 Date: Mon, 9 Nov 2026 16:55:51 +0000 Subject: [PATCH 2/4] docs: dcd mcp is in the binary, and MCP servers renew their login session Review follow-ups on the Connect an AI Agent page: - The pages that said the standalone binary has no MCP server meant dcd-mcp, which is still npm-only. They now say both installs have dcd mcp, and the dcd-mcp page points new setups at Connect an AI Agent. - The MCP servers renew a dcd login session as they run, so the warnings that a long-running server stops when the session expires were out of date (api-keys, dcd login, MCP Server). An API key is still the advice for agents that run unattended. - API keys gets an Access section (Full access, Device sessions only), which the agent page links to. - Connect an AI Agent says to update the CLI when dcd mcp, or a client in dcd mcp install, is missing. --- cli/dcd-login.md | 2 +- cli/overview.md | 2 +- getting-started/api-keys.md | 11 ++++++++++- mcp/connect.md | 6 +++--- mcp/overview.md | 10 +++++++--- 5 files changed, 22 insertions(+), 9 deletions(-) diff --git a/cli/dcd-login.md b/cli/dcd-login.md index 07b771b..51d2fef 100644 --- a/cli/dcd-login.md +++ b/cli/dcd-login.md @@ -82,4 +82,4 @@ The session from `dcd login` is written to: - `$XDG_CONFIG_HOME/dcd/config.json`, or - `~/.dcd/config.json` if `XDG_CONFIG_HOME` is not set -The file is created with `0600` permissions (owner read/write only) and holds your session tokens and the active team. When a command starts, the CLI refreshes the session if it's about to expire, so you should rarely need to log in again. A process that keeps running, such as the [MCP server](../mcp/overview.md), doesn't refresh its session, so use an API key for long-running processes. +The file is created with `0600` permissions (owner read/write only) and holds your session tokens and the active team. The CLI refreshes the session when it's about to expire, both when a command starts and while a process keeps running, such as the [MCP server](../mcp/connect.md), so you should rarely need to log in again. diff --git a/cli/overview.md b/cli/overview.md index 88050bd..af79f1e 100644 --- a/cli/overview.md +++ b/cli/overview.md @@ -2,7 +2,7 @@ The DCD CLI is the primary way to interact with DeviceCloud from your terminal or CI/CD pipeline. It is a drop-in replacement for `maestro cloud` — in most cases you can swap `maestro cloud` for `dcd cloud`. -The CLI is published as `@devicecloud.dev/dcd` on npm and as a standalone binary. The npm package also ships an [MCP server](../mcp/overview.md) (`dcd-mcp`) so AI agents can drive DeviceCloud directly. The standalone binary doesn't include the MCP server. +The CLI is published as `@devicecloud.dev/dcd` on npm and as a standalone binary. Both include `dcd mcp`, an [MCP server](../mcp/connect.md) that lets AI agents drive DeviceCloud directly. The npm package also ships `dcd-mcp`, the [older MCP server](../mcp/overview.md). ::: info **New in v5:** browser-based [`dcd login`](dcd-login.md) (no more passing a key on every command), a standalone binary installer with `dcd upgrade`, interactive [`dcd live`](dcd-live.md) device sessions, and an [MCP server](../mcp/overview.md). Existing API keys and `dcd cloud` usage continue to work unchanged. diff --git a/getting-started/api-keys.md b/getting-started/api-keys.md index 72f915f..8f6d8bd 100644 --- a/getting-started/api-keys.md +++ b/getting-started/api-keys.md @@ -16,7 +16,7 @@ This opens your browser, where you sign in (email OTP or Enterprise SSO) and aut - `$XDG_CONFIG_HOME/dcd/config.json`, or - `~/.dcd/config.json` if `XDG_CONFIG_HOME` is not set -The file is written with `0600` permissions (owner read/write only). When a command starts, the CLI refreshes the session if it's about to expire — you generally only log in again if you log out or switch machines. Long-running processes such as the [MCP server](../mcp/overview.md) don't refresh their session, so use an API key for those. +The file is written with `0600` permissions (owner read/write only). The CLI refreshes the session when it's about to expire, both when a command starts and while a process keeps running, such as the [MCP server](../mcp/connect.md). You generally only log in again if you log out or switch machines. ::: info No browser on the box (e.g. over SSH)? Run `dcd login --no-browser` and the CLI prints a URL to open elsewhere. @@ -34,6 +34,15 @@ In CI and other non-interactive environments, use an API key. 2. Open **Settings → API Keys** 3. Copy the key +### Access + +When you create a key, **Access** sets what it can do: + +- **Full access**: everything an API key can do. +- **Device sessions only**: for [AI agents](../mcp/connect.md). The key starts and drives device sessions and uploads builds and flows, but it can't start test runs or read their results. + +A key's access can't be changed after it's created. + ### Using an API key Set it as an environment variable so you don't have to pass it on every command: diff --git a/mcp/connect.md b/mcp/connect.md index 48c2381..fac6fbf 100644 --- a/mcp/connect.md +++ b/mcp/connect.md @@ -106,7 +106,7 @@ claude mcp add --scope user --transport http devicecloud https://api.devicecloud --header "Authorization: Bearer " ``` -When you create a key for an agent, choose **Device sessions only** under **Access**. That key can start and drive devices, but it can't start test runs or read their results. +When you create a key for an agent, choose **Device sessions only** under [Access](../getting-started/api-keys.md#access). That key can start and drive devices, but it can't start test runs or read their results. ## Through the CLI: `dcd mcp` @@ -120,7 +120,7 @@ When you create a key for an agent, choose **Device sessions only** under **Acce dcd mcp install claude-code # or claude-desktop, codex, cursor, vscode ``` -Leave out the client to pick from a list. Add `--read-only` for a server that offers only the tools that change nothing, or `--print` to see what it would add without changing anything. For Claude Code, Codex and VS Code it runs their own `mcp add` command. For Claude Desktop and Cursor it adds an entry to their config file and keeps everything else in it. Restart the app afterwards. +If your dcd has no `dcd mcp`, or `dcd mcp install` doesn't list your client, update the CLI first (`dcd upgrade`, or `npm install -g @devicecloud.dev/dcd` for the npm package). Leave out the client to pick from a list. Add `--read-only` for a server that offers only the tools that change nothing, or `--print` to see what it would add without changing anything. For Claude Code, Codex and VS Code it runs their own `mcp add` command. For Claude Desktop and Cursor it adds an entry to their config file and keeps everything else in it. Restart the app afterwards. ### Setting it up by hand @@ -170,7 +170,7 @@ codex mcp add devicecloud -- dcd mcp To run the npm package instead of an installed dcd, use `npx` as the command, with the arguments `-y`, `@devicecloud.dev/dcd` and `mcp`. That needs Node 22 or later. -`dcd mcp` signs in like the CLI: with your `dcd login` session, or with `DEVICE_CLOUD_API_KEY` set in the server's `env`. For read-only, add `--read-only` after `mcp` in the arguments, or set `DCD_MCP_READONLY=1`. +`dcd mcp` signs in like the CLI: with your `dcd login` session, which it renews as it runs, or with `DEVICE_CLOUD_API_KEY` set in the server's `env`. For an agent that runs unattended, such as in CI, use an API key. For read-only, add `--read-only` after `mcp` in the arguments, or set `DCD_MCP_READONLY=1`. ## Connected apps diff --git a/mcp/overview.md b/mcp/overview.md index ff04ac8..d2f54d2 100644 --- a/mcp/overview.md +++ b/mcp/overview.md @@ -1,5 +1,9 @@ # MCP Server +::: info +This page covers `dcd-mcp`, the older server. For new setups, use `dcd mcp` from the CLI or the hosted server: see [Connect an AI Agent](connect.md). +::: + The `@devicecloud.dev/dcd` package ships a second binary, `dcd-mcp` — a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents (Claude, Cursor, VS Code, and other MCP clients) drive DeviceCloud directly: list devices, submit cloud test runs, check status, and download artifacts. ::: warning @@ -29,7 +33,7 @@ Add the server to your MCP client's configuration. It runs over stdio via `npx` The `--package=` form matters: it tells `npx` to run the package's `dcd-mcp` binary. Without it, `npx` runs the `dcd` CLI instead, which rejects `dcd-mcp` as an unknown command. ::: info -The MCP server ships in the npm package only. The standalone `dcd` binary doesn't include it, so you need Node even if you installed the CLI with the binary installer. +`dcd-mcp` ships in the npm package only, so it needs Node even if you installed the CLI with the binary installer. The standalone binary has [`dcd mcp`](connect.md) instead, which serves the same tools. ::: ## Authentication @@ -43,8 +47,8 @@ When both are present, the environment variable wins. Credentials are resolved lazily on the first tool call, not at startup — so your client can connect and enumerate the tools before you've supplied a key, and a bad credential surfaces as a tool error rather than a server that won't start. -::: warning -The server resolves credentials once and reuses them for as long as it runs. A `dcd login` session is not refreshed after that, so a long-running server starts failing once the session expires, until you restart it. Use an API key for servers that stay running. +::: info +The server renews a `dcd login` session as it runs. If the session ends, for example after `dcd logout`, run `dcd login` again. You don't need to restart the server. For an agent that runs unattended, such as in CI, use an API key. ::: ## Tools From 391447ec17626ad3496fa150bc79cc5ee20b53b3 Mon Sep 17 00:00:00 2001 From: finalerock44 Date: Mon, 9 Nov 2026 17:15:06 +0000 Subject: [PATCH 3/4] docs: reword the Connect an AI Agent intro "gives an AI agent such as ... the tools to" ran the client list into the second object. It now reads "lets an AI agent, such as ..., drive cloud devices and run cloud tests". --- mcp/connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/connect.md b/mcp/connect.md index fac6fbf..f7cb0da 100644 --- a/mcp/connect.md +++ b/mcp/connect.md @@ -4,7 +4,7 @@ description: "Connect Claude Code, Cursor, VS Code, Claude Desktop, Codex or ano # Connect an AI Agent -DeviceCloud's [MCP](https://modelcontextprotocol.io) server gives an AI agent such as Claude Code, Cursor, VS Code, Claude Desktop or Codex the tools to drive cloud devices and run cloud tests. You connect it in one of two ways: +DeviceCloud's [MCP](https://modelcontextprotocol.io) server lets an AI agent, such as Claude Code, Cursor, VS Code, Claude Desktop or Codex, drive cloud devices and run cloud tests. You connect it in one of two ways: | | Install | Tools | Use it when | | --- | --- | --- | --- | From ff0833151551e17e8a1e2b62f1f0eca48435677b Mon Sep 17 00:00:00 2001 From: finalerock44 Date: Mon, 9 Nov 2026 18:30:47 +0000 Subject: [PATCH 4/4] docs: Connect an AI Agent covers dcd mcp only The page now covers dcd mcp, the MCP server in the CLI, for running cloud tests from an AI agent: setting it up with dcd mcp install, running it headless with an API key (for example in CI), configs by hand, its dcd_* tools and read-only mode, and the older dcd-mcp. The CLI Reference and MCP Server pages point at it the same way. --- cli/overview.md | 2 +- getting-started/api-keys.md | 9 --- mcp/connect.md | 128 ++++++++---------------------------- mcp/overview.md | 2 +- 4 files changed, 31 insertions(+), 110 deletions(-) diff --git a/cli/overview.md b/cli/overview.md index af79f1e..e696cbb 100644 --- a/cli/overview.md +++ b/cli/overview.md @@ -2,7 +2,7 @@ The DCD CLI is the primary way to interact with DeviceCloud from your terminal or CI/CD pipeline. It is a drop-in replacement for `maestro cloud` — in most cases you can swap `maestro cloud` for `dcd cloud`. -The CLI is published as `@devicecloud.dev/dcd` on npm and as a standalone binary. Both include `dcd mcp`, an [MCP server](../mcp/connect.md) that lets AI agents drive DeviceCloud directly. The npm package also ships `dcd-mcp`, the [older MCP server](../mcp/overview.md). +The CLI is published as `@devicecloud.dev/dcd` on npm and as a standalone binary. Both include `dcd mcp`, an [MCP server](../mcp/connect.md) that lets AI agents run cloud tests and read their results. The npm package also ships `dcd-mcp`, the [older MCP server](../mcp/overview.md). ::: info **New in v5:** browser-based [`dcd login`](dcd-login.md) (no more passing a key on every command), a standalone binary installer with `dcd upgrade`, interactive [`dcd live`](dcd-live.md) device sessions, and an [MCP server](../mcp/overview.md). Existing API keys and `dcd cloud` usage continue to work unchanged. diff --git a/getting-started/api-keys.md b/getting-started/api-keys.md index 8f6d8bd..e3b71fb 100644 --- a/getting-started/api-keys.md +++ b/getting-started/api-keys.md @@ -34,15 +34,6 @@ In CI and other non-interactive environments, use an API key. 2. Open **Settings → API Keys** 3. Copy the key -### Access - -When you create a key, **Access** sets what it can do: - -- **Full access**: everything an API key can do. -- **Device sessions only**: for [AI agents](../mcp/connect.md). The key starts and drives device sessions and uploads builds and flows, but it can't start test runs or read their results. - -A key's access can't be changed after it's created. - ### Using an API key Set it as an environment variable so you don't have to pass it on every command: diff --git a/mcp/connect.md b/mcp/connect.md index f7cb0da..34aea9c 100644 --- a/mcp/connect.md +++ b/mcp/connect.md @@ -1,128 +1,56 @@ --- -description: "Connect Claude Code, Cursor, VS Code, Claude Desktop, Codex or another MCP client to DeviceCloud, through the hosted MCP server or the dcd CLI." +description: "Connect Claude Code, Cursor, VS Code, Claude Desktop, Codex or another MCP client to DeviceCloud with dcd mcp, on your machine or headless in CI." --- # Connect an AI Agent -DeviceCloud's [MCP](https://modelcontextprotocol.io) server lets an AI agent, such as Claude Code, Cursor, VS Code, Claude Desktop or Codex, drive cloud devices and run cloud tests. You connect it in one of two ways: +`dcd mcp` is DeviceCloud's [MCP](https://modelcontextprotocol.io) server. It lets an AI agent, such as Claude Code, Cursor, VS Code, Claude Desktop or Codex, run cloud tests and read their results. It comes with the [CLI](../cli/overview.md), and it works the same on your machine and headless, such as in CI. -| | Install | Tools | Use it when | -| --- | --- | --- | --- | -| **Hosted**, `https://api.devicecloud.dev/mcp` | nothing | device tools | the agent drives cloud devices with apps and flows you've already uploaded | -| **`dcd mcp`**, through the CLI | the CLI | device tools and the `dcd_*` cloud-test tools | the agent also installs local builds, runs local flow files or runs cloud tests | - -::: info -The device tools are in beta, and need device sessions turned on for your organization: contact support to turn them on. If your team has them, **Settings → AI agents** in the console fills in everything on this page for you, with one-click install for Cursor and VS Code. -::: +You don't run it yourself. You add it to your MCP client's config, and the client starts it. ::: warning We accept no liability for anything your agent may read or execute. LLMs are a new technology: use them with care and at your own risk. ::: -## Hosted server - -The server is at `https://api.devicecloud.dev/mcp` (Streamable HTTP). The first time your client connects, it opens the DeviceCloud console in your browser: sign in, pick the organization the agent should use, and choose **Connect**. +## Set it up -### Claude Code +1. Install the CLI, as in the [Quick Start](../getting-started/quickstart.md). +2. Sign in with [dcd login](../cli/dcd-login.md). For an agent that runs without you, use an API key instead: see [Headless, with an API key](#headless-with-an-api-key). +3. Add the server to your client: ```bash -claude mcp add --scope user --transport http devicecloud https://api.devicecloud.dev/mcp +dcd mcp install claude-code # or claude-desktop, codex, cursor, vscode ``` -Then run `/mcp` in Claude Code and choose **devicecloud** to sign in. - -### Cursor - -Add the server to `~/.cursor/mcp.json`, next to any servers already in it: +If your dcd has no `dcd mcp`, or `dcd mcp install` doesn't list your client, update the CLI first (`dcd upgrade`, or `npm install -g @devicecloud.dev/dcd` for the npm package). Leave out the client to pick from a list. Add `--read-only` for a server that offers only the tools that change nothing, or `--print` to see what it would add without changing anything. For Claude Code, Codex and VS Code it runs their own `mcp add` command. For Claude Desktop and Cursor it adds an entry to their config file and keeps everything else in it. Restart the app afterwards. -```json -{ - "mcpServers": { - "devicecloud": { "url": "https://api.devicecloud.dev/mcp" } - } -} -``` +## Headless, with an API key -### VS Code +For an agent that runs without you, such as in CI or a script, sign in with an [API key](../getting-started/api-keys.md) instead of `dcd login`. Give it to the server as `DEVICE_CLOUD_API_KEY` in its environment. For example, for Claude Code in CI: ```bash -code --add-mcp '{"name":"devicecloud","type":"http","url":"https://api.devicecloud.dev/mcp"}' +claude mcp add --scope user devicecloud -e DEVICE_CLOUD_API_KEY="$DEVICE_CLOUD_API_KEY" -- dcd mcp ``` -Or add it to `.vscode/mcp.json`, or to your user `mcp.json` (**MCP: Open User Configuration** in the Command Palette): +In a JSON config, put it in the server's `env`: ```json { - "servers": { - "devicecloud": { "type": "http", "url": "https://api.devicecloud.dev/mcp" } + "mcpServers": { + "devicecloud": { + "command": "/Users/you/.dcd/bin/dcd", + "args": ["mcp"], + "env": { "DEVICE_CLOUD_API_KEY": "" } + } } } ``` -### Claude Desktop - -Open **Settings → Connectors** and choose **Add custom connector**. Name it DeviceCloud and paste `https://api.devicecloud.dev/mcp`. Claude Desktop's config file only takes servers that run on your machine, so the hosted server goes here. Free Claude plans allow one custom connector. - -### Codex - -```bash -codex mcp add devicecloud --url https://api.devicecloud.dev/mcp -codex mcp login devicecloud -``` - -Or add it to `~/.codex/config.toml`, then run `codex mcp login devicecloud`: - -```toml -[mcp_servers.devicecloud] -url = "https://api.devicecloud.dev/mcp" -``` - -The Codex CLI, IDE extension and ChatGPT desktop app share this file, so one setup covers all three. - -### Other clients - -Any client that supports Streamable HTTP and MCP sign-in (OAuth) can connect to `https://api.devicecloud.dev/mcp`. It finds the sign-in from the server's `401` response, registers itself, and opens the console for you to approve it. - -### Read-only - -Add `?read_only=true` to the URL for a server that offers only the tools that change nothing: `list_devices`, `get_device_status`, `inspect_screen`, `take_screenshot`, `get_command_status`, `get_logs`, `get_human_status` and `cheat_sheet`. Your agent can look at your organization's devices but can't start, drive or stop them. - -On a command line, quote the URL, because `?` is a wildcard in zsh, the default macOS shell: - -```bash -claude mcp add --scope user --transport http devicecloud 'https://api.devicecloud.dev/mcp?read_only=true' -``` - -::: warning -Read-only keeps an agent from changing anything by mistake. It isn't a permission: the same sign-in works on the URL without the flag. +::: info +Store the key as a secret in your CI provider (for example, a GitHub Actions secret). Never commit it to your repository. ::: -### With an API key - -For an agent that can't open a browser, such as one running in CI, send an [API key](../getting-started/api-keys.md) as a header instead of signing in: - -```bash -claude mcp add --scope user --transport http devicecloud https://api.devicecloud.dev/mcp \ - --header "Authorization: Bearer " -``` - -When you create a key for an agent, choose **Device sessions only** under [Access](../getting-started/api-keys.md#access). That key can start and drive devices, but it can't start test runs or read their results. - -## Through the CLI: `dcd mcp` - -`dcd mcp` runs on your machine and is started by your MCP client. It passes the hosted server's device tools through, and adds what only a local process can do: `install_app` takes `app_path`, a build on your machine, and `run` takes `path`, a flow file or a directory of flows. It also serves the `dcd_*` cloud-test tools from the [Tools Reference](tools.md). - -1. Install the CLI, as in the [Quick Start](../getting-started/quickstart.md). -2. Sign in with [dcd login](../cli/dcd-login.md). -3. Add the server to your client: - -```bash -dcd mcp install claude-code # or claude-desktop, codex, cursor, vscode -``` - -If your dcd has no `dcd mcp`, or `dcd mcp install` doesn't list your client, update the CLI first (`dcd upgrade`, or `npm install -g @devicecloud.dev/dcd` for the npm package). Leave out the client to pick from a list. Add `--read-only` for a server that offers only the tools that change nothing, or `--print` to see what it would add without changing anything. For Claude Code, Codex and VS Code it runs their own `mcp add` command. For Claude Desktop and Cursor it adds an entry to their config file and keeps everything else in it. Restart the app afterwards. - -### Setting it up by hand +## Setting it up by hand Start dcd by its **full path**. Desktop apps are usually opened from the Dock or Start menu, so they don't see the `PATH` your shell sets up, and a bare `dcd` fails with "command not found". The installer prints the path when it finishes. It's `~/.dcd/bin/dcd` by default, written out in full, because config files don't expand `~`. @@ -153,7 +81,7 @@ VS Code (`.vscode/mcp.json`, or your user `mcp.json`): } ``` -Codex (`~/.codex/config.toml`): +Codex (`~/.codex/config.toml`, shared by the Codex CLI, IDE extension and ChatGPT desktop app): ```toml [mcp_servers.devicecloud] @@ -170,12 +98,14 @@ codex mcp add devicecloud -- dcd mcp To run the npm package instead of an installed dcd, use `npx` as the command, with the arguments `-y`, `@devicecloud.dev/dcd` and `mcp`. That needs Node 22 or later. -`dcd mcp` signs in like the CLI: with your `dcd login` session, which it renews as it runs, or with `DEVICE_CLOUD_API_KEY` set in the server's `env`. For an agent that runs unattended, such as in CI, use an API key. For read-only, add `--read-only` after `mcp` in the arguments, or set `DCD_MCP_READONLY=1`. +`dcd mcp` signs in like the CLI: with your `dcd login` session, which it renews as it runs, or with `DEVICE_CLOUD_API_KEY`. + +## Tools -## Connected apps +`dcd mcp` serves the `dcd_*` tools: list devices, submit a cloud test run, follow its status and download its artifacts. The [Tools Reference](tools.md) describes each one. -Every client you sign in to the hosted server is listed under **Settings → Account → Connected apps**, with the organization it uses and when it was last used. **Disconnect** stops it working at once. Device sessions it starts run as you. +`dcd_run_cloud_test` starts a test run, which is billable. For an agent that should only look, add `--read-only` after `mcp` in the arguments, or set `DCD_MCP_READONLY=1`. The server then leaves out every tool that changes anything. ## The older `dcd-mcp` server -The npm package also has `dcd-mcp`, an older server with the `dcd_*` tools only. `dcd mcp` serves the same tools, so you only need `dcd-mcp` for a setup that already uses it. See [MCP Server](overview.md). +The npm package also has `dcd-mcp`, an older server with the same `dcd_*` tools. `dcd mcp` covers it, so you only need `dcd-mcp` for a setup that already uses it. See [MCP Server](overview.md). diff --git a/mcp/overview.md b/mcp/overview.md index d2f54d2..50731c5 100644 --- a/mcp/overview.md +++ b/mcp/overview.md @@ -1,7 +1,7 @@ # MCP Server ::: info -This page covers `dcd-mcp`, the older server. For new setups, use `dcd mcp` from the CLI or the hosted server: see [Connect an AI Agent](connect.md). +This page covers `dcd-mcp`, the older server. For new setups, use `dcd mcp` from the CLI: see [Connect an AI Agent](connect.md). ::: The `@devicecloud.dev/dcd` package ships a second binary, `dcd-mcp` — a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents (Claude, Cursor, VS Code, and other MCP clients) drive DeviceCloud directly: list devices, submit cloud test runs, check status, and download artifacts.