Skip to main content
ish has one backend and two independent ways to drive it: the ish CLI and the ish MCP server. You do not need both — neither depends on the other, and each works completely on its own. They speak to the same API, the same workspaces, the same studies, the same people, so if you do use both, anything you make in one is visible in the other. Pick the one surface that fits where your work already happens.
  • The CLI is the local surface. It is a binary you run in a shell, a CI job, or from a local coding agent like Claude Code or Cursor that can shell out. It runs on your machine, with access to your filesystem, your localhost, and your simulators — so it is the surface for local development and for testing apps you are running locally. You type ish study run, it prints a result, it exits with a code.
  • The MCP server is the hosted, agent-native surface. It exposes the same operations as tools that any MCP agent calls over https://mcp.ishlabs.io/mcp — including general assistants that have no access to your machine or filesystem at all. The agent runs studies inside its own loop and reads the results straight back. Good for “have an agent check this for me”, from wherever that agent lives.
Same engine underneath. Simulated people experience the thing you are making and report back what they noticed, where they got stuck, and what they would do next. The surface only changes how you ask — with one exception, below.

​
The shared model

Both surfaces operate on the same objects. Define each one once and reuse it everywhere:

Workspace

Where your studies, people, and credits live.

Study

The persistent research artifact, with iterations.

People

Reusable simulated personas grounded in who you build for.

Run vs ask

A full study run versus a lightweight ask.
Nothing here is CLI-only or MCP-only at the concept level. A study you create with the CLI shows up for the agent through the MCP, and the reverse. The aliases (w-…, s-…, a-…, tp-…, i-…, t-…) work on both, anywhere a UUID is expected.

​
The verb-to-tool map

The CLI reads as ish <noun> <verb>. The MCP exposes the same operations as <noun>_<verb> tools. The mapping is close to one-to-one. This table is the orientation, not the reference. For exact flags, parameters, and return shapes, follow the links to the generated reference.
The MCP tool to add an iteration is study_add_iteration. Older drafts call it study_iterate; that name is gone.
For the full CLI command tree, see the CLI overview. For every tool, tier, and resource, see the tool index and the resource reference.

​
What differs between the surfaces

The operations match. The ergonomics do not. Three differences matter.

​
Active context vs explicit ids

The CLI keeps a current context in ~/.ish/config.json: the workspace, study, and ask you last selected. ish workspace use w-abc sets the active workspace so later commands can omit it. ish status shows what is active. The MCP is stateless. Every tool takes the relevant workspace_id, study_id, or ask_id as a parameter, every time. There is no workspace_use tool, because there is nothing to remember between calls. The agent passes the id it is working with on each call.

​
Commands vs tools and resources

The CLI is all commands. The MCP splits its surface in two:
  • Tools are actions the agent invokes: study_run, ask_run, person_generate.
  • Resources are static reads addressed by a URI: ish://identity/me, ish://docs/<slug>, ish://study/<id>/screenshots. They are what the CLI exposes as read commands like ish status and ish docs get-page.
The hosted server exposes 40 tools, 10 resources, and no prompts. A resource read on the MCP is the same data a --json read returns on the CLI.

​
Output for a parser

The CLI prints for a human by default and switches to JSON when piped, or when you pass --json. The --get flag extracts a single field. See global flags for the full output contract. The MCP always returns structured data to the calling agent. The agent reads it directly; there is no human-formatting step.

​
What is MCP-only

A few operations exist only as MCP tools. They have no CLI command today.
Patch a study’s top-level metadata: name, description, status, modality, content_type, assignments, and interview questions. Only the fields you pass change; the rest stay untouched, and iterations are left alone (edit those with study_update_iteration or study_add_iteration). The MCP exposes it as a write-tier tool; the CLI has no ish study revise verb. See study tools.
Clone a study’s shape (name, description, assignments, interview questions) into one or more competitor brand workspaces so you can compare the same setup across audiences. It does not copy iterations, participants, or frames, and it does not run anything: each clone is a draft with an empty placeholder iteration you fill in, then study_run yourself. The source and the brands must share a parent workspace. A long-running tool with no CLI equivalent. See study tools.
connect runs the other way. The ish connect CLI command exposes your localhost to ish’s remote simulators through a Cloudflare tunnel, and works anywhere. The MCP connect tool does the same thing, but only when you run the MCP server on your own machine. The hosted server’s localhost is the cloud host’s loopback, not yours, so it refuses with a validation error. To let simulated people experience a local dev server through an agent, use the ish connect CLI on the same machine.

​
What only the CLI can do

Because the CLI runs on your machine and the hosted MCP server does not, testing an app that runs locally is a CLI capability. ish study run --local drives the artifact on your own machine — a web app through Playwright, an Android app on an emulator, or an iOS app in the Simulator — and nothing leaves your laptop. The hosted MCP server has no path to your machine, your localhost, or your simulators, so it cannot do this. The one bridge is the tunnel: ish connect <port> exposes a local web build to ish’s cloud simulators, and an agent on the hosted MCP can then point a study at the tunnel URL (platform="code"). That still needs the ish CLI running on the same machine — the MCP alone never reaches your localhost. Native iOS and Android runs stay CLI-only.

​
Which surface to use

Reach for the CLI

You work locally — at a shell, in CI, or through a local coding agent that can shell out. You need to test something running on your own machine: a localhost web build, an iOS app, an Android app. You want JSON to pipe into another tool; one command, one result, one exit code.

Reach for the MCP

You drive ish from an agent — including a hosted assistant with no access to your machine. You want it to run a study inside its own loop and read the result straight back, without leaving wherever it lives.
You never need both — each surface stands on its own. But they share one backend, so you can mix them when it helps: create a study from the CLI, let an agent run iterations through the MCP, read the results back in either. Same backend, same objects, same findings.

​
Next

CLI quickstart

Install the CLI and run your first study in under five minutes.

Connect an agent

Point an MCP client at the hosted server.

CLI overview

The full command tree and conventions.

MCP overview

Tools, resources, and tool conventions.