Kobiton AI plugin and tools reference The Kobiton automate plugin connects AI coding assistants to Kobiton. Supported hosts are Claude Code, Claude Desktop, GitHub Copilot CLI, Gemini CLI, Codex CLI, Cursor CLI, and Cursor IDE. The plugin ships MCP tools, skills, and commands covering device management, app uploads, test case and test suite management, test execution, and session review. This reference covers automate plugin version 1.13.0. For newer changes, see the automate GitHub repo. MCP tools The plugin exposes 41 MCP tools across 5 domains. Devices Tool Description listDevices List available devices, filtered by platform, availability, device group, name, UDID, or group ID. Returns device name, UDID, platform, OS version, availability, and an is_cloud flag. Pass virtualUsb: true to list the private devices that are ready for virtualUSB. getDeviceStatus Get the real-time status of one device, including availability, current session, battery level, and connection state. reserveDevice Reserve a device for exclusive use during testing. Returns the reservation ID that terminateReservation requires. terminateReservation Release a reserved device by terminating its reservation. listHostingMachines Organization admins only. List host machines with each machine’s virtualUSB status, the next step when virtualUSB is not ready, and its max parallel tests. Filter by device UDID or machine ID. configureHostingMachine Organization admins only. Enable or disable virtualUSB, choose routing, and set max parallel tests on one host machine. Makes the same change as Device Management in Kobiton Portal. listDevices matches deviceName case-insensitively against the full device name. Use * wildcards for partial matches. Value Matches galaxy Any name containing "galaxy", such as Galaxy S22+ and Galaxy Tab S8 Galaxy* Any name starting with "Galaxy" Galaxy S22+ Only the device whose full name is Galaxy S22+ A value without wildcards matches the exact full name only, so Galaxy on its own returns no devices. The --name filter in Kobiton CLI uses the same convention. When every device list in the response is empty, listDevices returns an applied_filters object that echoes the filter values it used. Check it to tell a filter that matched no devices apart from an organization that has no devices to list. Devices returned with is_cloud: true have restricted shell-command access in CLI sessions. Devices returned with is_cloud: false are unrestricted. For the virtualUsb filter on listDevices, the admin-only listHostingMachines and configureHostingMachine tools, and their response fields, see virtualUSB MCP tools. For the same settings in Kobiton Portal, see Device Management page. Sessions Tool Description listSessions List test sessions, filtered by state, device, platform, and date range. Returns session ID, state, device information, duration, and timestamps. getSession Get session details, including commands, capabilities, and metadata. getSessionArtifacts Get download URLs for a session’s video, logs, screenshots, and reports. getUserInputEvents Get the touch and swipe gestures performed in device-only live view during a session. terminateSession Stop a running test session. startNativeSession Start a native automation session with XCUITest, UIAutomator, or GameDriver. Upload the app and the test runner to Kobiton Store first, then pass their kobiton-store: identifiers. This books a device and starts a billable session. listAccessibilityValidations List a session’s accessibility findings. Filter by finding type with type, which accepts TOUCH_TARGET_SIZE, COLOR_CONTRAST, and CONTENT_LABELING. getAccessibilityValidationsSummary Get a session’s accessibility counts by finding type and issue name, with the number of steps scanned and the time of the latest finding. The summary carries no findings. listCrashValidations List a session’s crash findings. listResponseTimeValidations List a session’s response time findings. listBlockerValidations List a session’s blocker findings. listElementSelectionValidations List a session’s element selection findings. listFlexCorrects List a session’s Flex Correct findings. The validation tools read the findings that Session Explorer shows in Test Result Analysis. See Review test result analysis and Validate accessibility. Each list tool takes sessionId, limit, and offset. limit defaults to 10 and is clamped to 20, so a single call never returns more than 20 findings. Responses return items alongside page, total_pages, and total_items, so an assistant pages through a large session one validation type at a time instead of pulling every finding into context. A session with no findings of the requested type returns total_items: 0 and an empty items array, not an error. An unknown or inaccessible session returns a tool error. listAccessibilityValidations returns lean items by default. Use the include parameter to add the element, metadata, screen, and screenshot URL fields. Ask for validations in natural language. The assistant selects the tool from the tool descriptions, so requests such as "did the app crash" or "show accessibility issues" route to the matching tool. Apps Tool Description listApps List uploaded app builds in your organization. uploadAppToStore Upload an app to Kobiton Store. Uploaded apps are permanent and visible in Kobiton Portal. confirmAppUpload Confirm an uploaded file so Kobiton creates the app record. Parsing runs asynchronously, so the record is not immediately complete. getAppParsingStatus Check the parsing status of an uploaded app version until it reaches a terminal state. getApp Get app details and version history. Test management A test case is a saved, replayable sequence of steps created from a completed session. A test suite is an ordered collection of test cases. A test run executes a test case or a suite across one or more devices and reports results per device. Every test case, test suite, and test run belongs to one team, or to the organization level when it has no team. Responses carry team_id, where null means organization level. No list tool returns items from more than one team in a single call. The teamId parameter on listTestCases, listTestSuites, and listTestRuns works differently for each role. Role teamId on the list tools Organization admin Optional. Omit it to list organization-level items only. Pass a teamId to list that team’s items. Organization member Required. The API returns Team id is required without it. Call listTeams to get your team ids, then retry with one of them. Reuse the team_id returned on a listed item when you compose suites and runs. Test suites and test runs are team-homogeneous: every test case in a suite belongs to the suite’s team, and a run’s suite or selected test cases all belong to one team. Tool Description saveTestCase Convert a finished manual session into a reusable test case. The new test case inherits the source session’s team. A session with no team produces a test case at the organization level, which organization members cannot list. listTestCases List test cases, filtered by team, keyword, or platform. getTestCase Get test case details, including its steps. updateTestCase Update a test case’s name, description, or steps. deleteTestCase Delete a test case. createTestRun Create a test run from a test suite or from selected test cases. The suite or the selected test cases all belong to one team. listTestRuns List test runs, filtered by team, keyword, or platform. Sort the results with sortBy, which accepts the uppercase values NAME and CREATED_AT. getTestRun Get test run details, including its sessions. terminateTestRun Stop a running test run. listTestSuites List test suites, filtered by team or keyword. getTestSuite Get test suite details, including member test cases. createTestSuite Create a test suite from existing test cases. Every test case added belongs to the suite’s team. Organization admins may omit teamId to create the suite at the organization level. Organization members pass a team they belong to. updateTestSuite Update a test suite’s name, description, or membership. deleteTestSuite Delete a test suite. Member test cases are kept. Account Tool Description getCredential Return your username, portal URL, and a one-time setup token. The tool does not return your API key. Backs the /automate:setup command, so no manual file editing is required. getOrgSettings Return your organization’s settings, including the live remediation flag that determines what happens when a test run execution hits a blocker. listTeams Return the teams you belong to as a groups array. Use it to scope a test management list call as an organization member, or to recover from Team id is required. An empty array means you belong to no team. Ask an organization admin to assign you to one. AI tool attribution Kobiton records which AI tool made each MCP call, and stores that name on sessions started with startNativeSession. The server resolves the name from the request itself, so no tool accepts it as an argument and no prompt or skill has to supply it. The server checks, in order: The X-AI-Tool-Name header, when your MCP server configuration sets it. The User-Agent sent by your AI assistant, when the header is absent. Unknown, when neither identifies a recognized tool. An unrecognized value never fails a call. The call runs normally and Kobiton records the tool as Unknown. Set X-AI-Tool-Name to attribute your calls explicitly. The Codex CLI and Cursor CLI setup guides already include this header in their MCP configuration examples. See Install and configure local plugin and Kobiton for Cursor CLI. Skills The plugin ships six guided skills. Using these skills in Claude Desktop requires a Claude Code subscription. Skill Description run-automation-suite Run local Appium test scripts against Kobiton devices. Covers app upload, device selection, capability parsing, local execution, and result collection. Supports Node.js, Python, .NET, and Java. run-interactive-session Interact with a device using natural language. Translates intent into CLI commands for WebDriver actions (find elements, type, click, swipe), device operations (adb shell, screen capture, port forwarding), file transfer, app management, and test execution. drive-automation-session Drive a reserved device through a flow you describe. Opens an automation session against Kobiton WebDriver hub and works through the flow one action at a time. Save the resulting session as a test case with saveTestCase. create-test-run Create a test run from a test case or a test suite. Fills in defaults, confirms a summary before creating the run, then offers to monitor it. monitor-test-run Watch a running test run and report state changes. Surfaces the live remediation URL when an execution is blocked, and reports a blocked execution as blocked rather than passed. debug-device-over-vusb Debug an app on a private Kobiton device connected to your computer over virtualUSB. Installs the pinned virtualUSB client, connects the device so it appears in adb or Xcode, runs the install, reproduce, and capture-logs loop, and always disconnects the device at the end. See Debug over virtualUSB. Choose a skill Goal Skill Run Appium scripts you already have on Kobiton devices run-automation-suite Exercise a flow hands-off and save it as a test case to rerun later drive-automation-session Inspect or troubleshoot a device directly, pull logs, push files run-interactive-session Start a test run from an existing test case or suite create-test-run Follow a running test run and catch blockers monitor-test-run Debug your app on a private device with your local adb or Xcode debug-device-over-vusb Skill requirements by host Skills differ in what they need from the host running them. Check the requirement, not the host name: a chat surface with code execution provides a filesystem and Node.js and still cannot run the credential-dependent skills, because nothing there runs /automate:setup to write ~/.kobiton/.credentials. Skill Local file access Credentials file Platform Runs on an MCP connection alone create-test-run No No Any Yes monitor-test-run Yes Yes Any, with Node.js 18 or later No drive-automation-session Yes Yes Any, with Node.js 18 or later No run-automation-suite Yes No Any, with Node.js 18 or later, Appium 2.x, and your script’s language runtime No run-interactive-session Yes Yes macOS only No debug-device-over-vusb Yes Yes macOS or Windows No create-test-run is the only skill that runs with nothing but an authenticated MCP connection. If you opt into monitoring, it hands off to monitor-test-run, which needs local file access and the credentials file. On a host without those, create the run and note its ID instead of watching it. monitor-test-run reports progress best when the host streams output from a background command. Without that, it falls back to a foreground loop rather than refusing to run. For debug-device-over-vusb requirements, client setup, flow, and troubleshooting, see Debug over virtualUSB. All MCP tools and the run-automation-suite skill work on every platform your host supports. The run-interactive-session skill ships a CLI binary built for macOS as a single-architecture x86_64 executable. It runs natively on Intel Macs and under Rosetta 2 on Apple Silicon. No Linux or Windows build ships. On those platforms, use run-automation-suite or drive-automation-session, or call the MCP tools directly. Commands Command Description /automate:setup Write your Kobiton credentials to ~/.kobiton/.credentials without your API key passing through the AI assistant. See Setup and your API key. Also installs the ~/.kobiton/bin/kobiton CLI wrapper used by run-interactive-session. /automate:doctor Read-only diagnostic for the CLI installation, credentials file, active profile, and required fields. Also reports the pinned and installed virtualUSB client versions. Prints remediation hints for any failures. On Cursor CLI and Cursor IDE, plugin commands register without a namespace prefix, so these appear as /setup and /doctor. Select the entry with the Kobiton description to tell them apart from Cursor’s built-in commands. Claude Code and Codex CLI recreate the Kobiton CLI wrapper symlink at the start of every new session. On Codex CLI, the first session prompts you to trust the hook once through /hooks. On GitHub Copilot CLI and Gemini CLI, the symlink is not recreated automatically. Run /automate:setup once after install to create the wrapper, and run it again if the symlink goes missing. On Cursor CLI, the symlink is not recreated automatically. Run /setup once after install to create the wrapper, and run it again if the symlink goes missing. Setup and your API key A local setup script fetches your API key directly from Kobiton and writes it to ~/.kobiton/.credentials. The AI assistant conversation shows only a one-time setup token and the last 4 characters of the key. Setup uses a dedicated API key named kobiton-mcp-<assistant>, for example kobiton-mcp-claude. The first setup creates the key, and later setups reuse it. Your other API keys are not changed. Older plugin versions stop before setup runs and ask you to update the plugin. Update the plugin, then run setup again. An existing ~/.kobiton/.credentials file keeps working without running setup again. Setup in older plugin versions recorded the full API key in the AI assistant conversation. If you shared the conversation from one of those setup runs, rotate that API key in Kobiton Portal > Settings > API Keys. See Manage your API credentials. Test execution The run-automation-suite skill guides you through the full test lifecycle: Upload or select an app Select a device Parse capabilities from your script Run the test in the background Surface the live session URL and collect artifacts (video, logs, screenshots, reports) Supported languages: Language Extension Command Node.js .js node <script> <udid> Python .py python <script> <udid> .NET .cs / .csproj dotnet test Java .java mvn test or java -cp … Example prompts Device management Show available Android devices Check if Galaxy S23 is available Reserve Pixel 6 for 60 minutes Release my reserved Pixel 6 App management Show uploaded Android apps Upload resources/apps/GS.apk Check whether app version 12345 finished parsing Get details for app version 12345 Test execution Run tests/smoke_test.js on a Pixel device Run my Appium suite under tests/ on an iPhone 15 Driving a device through a flow Open my app on the reserved device, log in, and add the first item to the cart Drive the checkout flow on the reserved Pixel 6 Interactive testing Tap the Login button on the current session Type "hello" in the search field Swipe down to refresh Pull /sdcard/Download/report.txt from the device Run adb shell pm list packages on the current device Debugging over virtualUSB Debug the login crash in my app on a private Android device over virtualUSB Install build.apk on my private Pixel over virtualUSB, reproduce the checkout freeze, and show the logs Test cases and test runs Show my teams Save session 51234 as a test case named smoke-add-to-cart List my Android test cases Create a test run for smoke-add-to-cart on 3 Android devices Watch test run 8891 and tell me if anything blocks Stop test run 8891 Debugging over virtualUSB Which of my private devices are ready for virtualUSB Is device <udid> ready for virtualUSB Show virtualUSB status for my host machines Connect a private Pixel over virtualUSB, install app-debug.apk, reproduce the crash on launch, and show me the logs Session validations Did the app crash in session 12345 Show accessibility issues for session 12345 Summarize the accessibility findings for session 12345 Show color contrast findings for session 12345 with screenshots List slow responses in session 12345 Session management Show running sessions Get details for session 12345 Start a UIAutomator session on a Pixel 8 with my uploaded app and test runner Download logs from the last failed session Stop session 12345