# Overview

The QPilot MCP Server connects your Pcloudy testing environment directly to an MCP-compatible AI assistant (such as Claude Desktop, Cursor, or Claude Code). Once configured, you can drive Pcloudy using plain natural-language prompts — no scripts or manual navigation required.

With the integration enabled, your AI assistant can:

* Query the live Pcloudy device list (real Android, iOS, and browsers)
* Start a Playground session on an available real device
* Pull and run your QPilot test cases
* Retrieve session details, live-view URLs, and recordings

## Prerequisites

1. An active Pcloudy account with API access enabled.
2. Your Pcloudy username (registered email) and API Access Key.
3. An MCP-compatible AI client installed — e.g. Claude Desktop, Cursor, or Claude Code.
4. A runtime for the server if running locally (e.g. Python 3.10+ with uv/uvx). Confirm the exact requirement from the configuration page.

## Step 1 — Get your Pcloudy API Access Key

1. Sign in to your Pcloudy account.
2. Open Settings / My Account and locate the API Access section.
3. Generate or copy your API Access Key. Keep it secure — it authenticates the MCP server on your behalf.

## Step 2 — Open your MCP client configuration

* Claude Desktop
  1. Go to Settings → Developer → Edit Config. This opens (and creates, if needed) claude_desktop_config.json.
  2. macOS: \~/Library/Application Support/Claude/claude_desktop_config.json
  3. Windows: %APPDATA%\Claude\claude_desktop_config.json
* Cursor
  * Open Settings → MCP, or edit .cursor/mcp.json in your project.
* Claude Code
  * Use the CLI: claude mcp add — then supply the Pcloudy command and arguments.

## Step 3 — Add the Pcloudy MCP server

Add the following entry inside the mcpServers object, then replace each \<placeholder> with your value:

```bash
{ 

  "mcpServers": { 

    "Pcloudy": { 

      "command": "<command, e.g. uvx>", 

      "args": ["<Pcloudy-mcp-package-or-path>"], 

      "env": { 

        "PCLOUDY_USERNAME": "<your-Pcloudy-email>", 

        "PCLOUDY_API_KEY": "<your-api-access-key>", 

        "PCLOUDY_BASE_URL": "<your-Pcloudy-cloud-url>" 
      } 
    } 
  } 
} 

```

> **Tip:**
>
> **Tip:** If you already have other servers in mcpServers, add the “Pcloudy” block alongside them — do not create a second mcpServers object, and watch for trailing commas.

## Step 4 — Save and restart

* Save the configuration file.
* Fully quit the client (Cmd+Q on macOS / Quit from the tray on Windows) — do not just minimize.
* Reopen the client. The server starts in the background; no confirmation message is shown.

## Step 5 — Verify the connection

* Open a new chat and look for the tools (hammer) icon — the Pcloudy tools should be listed there.
* Or simply ask: “List my available Pcloudy devices.” If the device list returns, the integration is working.

> **Info:** Configuration complete: Once the configuration is done, your Claude is fully configured and ready to control Pcloudy. Just open a new chat and type your instruction in plain English — a few sample prompts are below.

## Using the integration/Sample Prompt

Once connected, type instructions in plain English. The assistant calls the Pcloudy tools, selects a device, and acts on your behalf. Example prompts:

| Prompt                                                         | What Happens                                                      |
| -------------------------------------------------------------- | ----------------------------------------------------------------- |
| “Create a playground session on any available high-end device” | Selects a free high-end (premium) device and opens a live session |
| “Fetch all the steps of this session                           | Will list all the step                                            |
| “Execute steps 3 to 5                                          | It will execute these steps only                                  |
| “Delete step 2”                                                | I will delete the steps                                           |
| “Show me all available iOS devices”                            | Returns the current list of free real iOS devices                 |
| “Run my QPilot login test on a Pixel device”                   | Locates the test, attaches a device, and executes it              |

[Video: Overview](https://www.youtube.com/watch?v=EjyExRW0Zv0)

[Video: Overview (2)](https://www.youtube.com/watch?v=-sfbYagntBY)

## Troubleshooting

* No tools appear: ensure you fully quit and reopened the client; validate the JSON for trailing commas or missing braces (e.g. at jsonlint.com).
* Authentication / API error: re-check your username and API Access Key. The assistant can refresh authentication and retry — if it persists, regenerate the key in Pcloudy.
* Device not found or busy: the device may be in use; ask the assistant to list currently available devices and pick another.
* Wrong cloud URL: confirm PCLOUDY_BASE_URL matches your Pcloudy environment.