> For the complete documentation index, see [llms.txt](https://docs.devicecloud.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devicecloud.dev/ai-agents-and-mcp/overview.md).

# MCP Server

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.

{% hint style="warning" %}
The MCP server is a new, beta capability. The tool surface may change.
{% endhint %}

{% hint style="warning" %}
Please note that we accept no liability for anything your agent(s) may read or execute when using our MCP server. LLMs are a new technology and should be used with caution at your own risk.
{% endhint %}

## Setup

Add the server to your MCP client's configuration. It runs over stdio via `npx` (Node 22 or newer), so there's nothing to install separately:

```jsonc
{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "--package=@devicecloud.dev/dcd", "dcd-mcp"],
      "env": { "DEVICE_CLOUD_API_KEY": "<your-api-key>" }
    }
  }
}
```

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.

{% hint style="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.
{% endhint %}

## Authentication

Auth is inherited from the CLI:

* Set `DEVICE_CLOUD_API_KEY` in the server's `env` (as above) — **recommended**, **or**
* Run [`dcd login`](/cli-reference/dcd-login.md) once and the server will pick up the stored session.

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.

{% hint style="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.
{% endhint %}

## Tools

The server exposes five tools. Four are read-only; `dcd_run_cloud_test` submits a run and is billable.

| Tool                                                                           | What it does                                                     |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [`dcd_list_devices`](/ai-agents-and-mcp/tools.md#dcd-list-devices)             | Discover available devices, OS versions, and Maestro versions    |
| [`dcd_list_runs`](/ai-agents-and-mcp/tools.md#dcd-list-runs)                   | List recent test runs (filter by name/date, paginated)           |
| [`dcd_get_status`](/ai-agents-and-mcp/tools.md#dcd-get-status)                 | Get the status and per-test results of a run                     |
| [`dcd_download_artifacts`](/ai-agents-and-mcp/tools.md#dcd-download-artifacts) | Download a run's artifacts zip, and optionally a report, to disk |
| [`dcd_run_cloud_test`](/ai-agents-and-mcp/tools.md#dcd-run-cloud-test)         | Submit a flow to run on the cloud (**billable**)                 |

See [Tools Reference](/ai-agents-and-mcp/tools.md) for every parameter, default, and return shape.

## Read-only mode

`dcd_run_cloud_test` consumes test credits, so it's annotated as a destructive/non-read-only tool so well-behaved clients can (and should) prompt before calling it. To hide it entirely (recommended for autonomous or untrusted agents), either:

* pass `--read-only` in `args`, or
* set `DCD_MCP_READONLY=1` in `env`.

The remaining tools are all read-only. A read-only server doesn't just refuse the tool — it never advertises it, so an agent can't attempt a billable run at all:

```jsonc
{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "--package=@devicecloud.dev/dcd", "dcd-mcp", "--read-only"],
      "env": { "DEVICE_CLOUD_API_KEY": "<your-api-key>" }
    }
  }
}
```