# NthCase documentation

> Natural-language tests on real iOS, Android and web devices — describe, compile, run, read the evidence.
> Machine surfaces: the nth CLI, an MCP server (46 tools), and the machine-reachable REST API,
> all on a workspace API key or, for the MCP server, a person's sign-in (available on the Pro and Team plans, checked on every request).
> The MCP server is hosted at https://mcp.nthcase.com/mcp, with nothing to install. An AI tool that supports MCP connects to it in one of two ways.
> It signs in (OAuth): the person signs in to NthCase, picks one workspace and allows the connection, and no key is copied.
> Or it sends a workspace API key on every request as `Authorization: Bearer gp_…`; a client that runs only local servers sends it through `npx mcp-remote https://mcp.nthcase.com/mcp --header "Authorization: Bearer gp_…"`.
> For example, claude.ai and Claude Desktop sign in as a custom connector: Add custom connector → paste the URL → sign in → Allow. Claude Code adds it with `claude mcp add --transport http nth https://mcp.nthcase.com/mcp` and signs in through /mcp. Cursor sends the key.
> In an AI tool that supports MCP Apps, such as claude.ai, Claude Desktop and ChatGPT, trigger_run opens a panel in the chat that follows the run: the device live while it runs, each step as it passes, fails or waits, the credits so far and the verdict. When a device cannot be watched, the panel says why.
> An AI tool that does not support MCP Apps loses nothing: trigger_run answers it with the run and tells the model to poll get_run until the run ends, and its tool list may show the panel's own three tools, get_run_live_state, mint_run_mirror_url and mint_run_picture_url, which only read.
> A mobile app's build FILE is uploaded from your own machine: `nth builds upload <path> --platform <Android|iOS>`, or upload_build on
> a locally run MCP server — the hosted one cannot read your disk. The upload answers with a build id; register_target and use_build take it.

## Get started

- What NthCase is: /docs
  - The loop: /docs#the-loop
  - The surfaces: /docs#the-surfaces
- Your first test in 5 minutes: /docs/quickstart
  - 1 · Redeem a code: /docs/quickstart#subscribe
  - 2 · Register your app: /docs/quickstart#register
  - 3 · Optional: Discovery: /docs/quickstart#discover
  - 4 · Write & compile: /docs/quickstart#write-compile
  - 5 · Run & read the evidence: /docs/quickstart#run
  - 6 · Put it in CI: /docs/quickstart#ci
- How a run is priced: /docs/pricing
  - The credit: /docs/pricing#the-credit
  - What a run costs: /docs/pricing#run-charge
  - A device you connected yourself: /docs/pricing#your-own-device
  - A run that reaches no verdict: /docs/pricing#no-verdict
  - Other operations: /docs/pricing#other-operations
  - Discovery is quoted: /docs/pricing#discovery-price
  - Budgets & top-ups: /docs/pricing#budgets
  - Estimates err high: /docs/pricing#estimates

## Concepts

- Concepts: /docs/concepts
  - Apps & targets: /docs/concepts#apps-targets
  - Scenarios & compiled plans: /docs/concepts#scenarios-plans
  - Runs & evidence: /docs/concepts#runs-evidence
  - Discovery: /docs/concepts#discovery
  - Scope: /docs/concepts#scope
  - Credits, budgets & plans: /docs/concepts#credits-budgets
  - Models: /docs/concepts#models
  - Self-healing & pinning: /docs/concepts#self-healing
  - Schedules & cycles: /docs/concepts#schedules
  - Visual baselines: /docs/concepts#visual-baselines

## Credentials and files

- Credentials and files: /docs/credentials-and-files
  - Credentials: /docs/credentials-and-files#credentials
  - Where a secret is decrypted: /docs/credentials-and-files#where-decrypted
  - Your files: /docs/credentials-and-files#your-files
  - Deleting a file: /docs/credentials-and-files#deleting-a-file
  - Your files are not a run's files: /docs/credentials-and-files#two-shelves
  - From CI, the CLI and the MCP server: /docs/credentials-and-files#machine-surfaces

## Your own devices

- Connect your own devices: /docs/your-devices
  - What the agent is: /docs/your-devices#what-it-is
  - Getting the binary: /docs/your-devices#get-it
  - The token: /docs/your-devices#token
  - The commands: /docs/your-devices#commands
  - What doctor answers: /docs/your-devices#doctor
  - When your phone is shown live: /docs/your-devices#no-live-view
  - Network capture on your own phone: /docs/your-devices#network-capture
  - What stays running on your phone: /docs/your-devices#after-a-run
  - What a run costs: /docs/your-devices#cost
  - Running on your own iPhone: /docs/your-devices#iphone-setup
  - Not supported yet: /docs/your-devices#not-yet
- Devices you rent from a cloud lab: /docs/cloud-lab
  - Rows in your workspace: /docs/cloud-lab#rows
  - Your key stays on your machine: /docs/cloud-lab#your-key
  - First, your build: /docs/cloud-lab#your-build
  - Which devices: /docs/cloud-lab#which-devices
  - What a run on one costs: /docs/cloud-lab#lab-cost
  - Day two: /docs/cloud-lab#day-two

## CLI

- CLI: /docs/cli
  - Install: /docs/cli#install
  - Auth: /docs/cli#auth
  - Commands: /docs/cli#commands
  - Exit codes: /docs/cli#exit-codes
  - CI recipe: /docs/cli#ci-recipe

## MCP server

- MCP server: /docs/mcp
  - Watch a run in the chat: /docs/mcp#live-run
  - What you can ask: /docs/mcp#ask
  - Connect your AI tool: /docs/mcp#connect
  - Tool reference: /docs/mcp#tools
  - Cost & safety: /docs/mcp#cost-safety

## REST API

- REST API: /docs/rest
  - Authentication: /docs/rest#authentication
  - Runs: /docs/rest#runs
  - Datasets: /docs/rest#datasets
  - Files: /docs/rest#files
  - Builds: /docs/rest#builds
  - Scenarios & plans: /docs/rest#scenarios
  - Schedules: /docs/rest#schedules
  - Targets & discovery: /docs/rest#targets-discovery
  - Devices: /docs/rest#devices
  - Workspace: /docs/rest#workspace

## Policies

- Privacy Policy: /privacy
- Terms of Service: /terms