# Usercase (npm · @usercase/mcp)

Ask real users on your site and run virtual users in a real browser, then fix what they hit.

- Trust score: 64/100 (medium)
- Change this week: +19
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- npm · `@usercase/mcp`: 64/100 (this document), [markdown](https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp.md), [page](https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp)

## Channel facts

- Registry: `npm`
- Package: `@usercase/mcp`
- Version: `0.2.17`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 31 of 96 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 6/100
  - Repository check failed: no source repository is declared.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (UNLICENSED) isn't a recognized OSI-approved license.
  - Actively maintained (last published 5 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 78/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4635 tokens (~136/item across 34 items; 34 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 90/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 70% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "steps_send" implies "send" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 35 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the Usercase MCP server?

Usercase runs locally as an npm package, launched with npx -y @usercase/mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add io-usercase-mcp -- npx -y @usercase/mcp
```

### Cursor

```json
{
  "mcpServers": {
    "io-usercase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@usercase/mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "io-usercase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@usercase/mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add io-usercase-mcp -- npx -y @usercase/mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "io-usercase-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@usercase/mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add io-usercase-mcp --command npx --arg -y --arg @usercase/mcp
```

### Hermes

```yaml
mcp_servers:
  io-usercase-mcp:
    command: "npx"
    args: ["-y", "@usercase/mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "io-usercase-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@usercase/mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add io-usercase-mcp -t stdio -c npx -a -y @usercase/mcp
```

### Other

```json
{
  "mcpServers": {
    "io-usercase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@usercase/mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 64, +1)

No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-19 (score 63, +1)

No change was recorded against any check on this day. Stability & Change Management went from 13 to 17. That category is still filling its 30-day observation window: 4 days of observed history at the previous scan, 5 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-17 (score 62, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-15 (score 61, +16)

- [security improvement] Malware scan: unverified → pass
- [functional improvement] Stability: unverified → 0.03
- [functional] Package version: 0.2.15 → 0.2.17
- [functional] Package version: 0.2.15 → 0.2.16

### 2026-11-14 (score 45)

First indexed and scored.

## MCP tools (34)

### `check_site` (~115 tokens)

Open the site once as a virtual user and report: does it load, is the Usercase SDK running (which project), is a firewall/bot protection blocking us (and how to unblock, per vendor), is the secret key set. Always run this before starting visits. If it reports a block, stop and tell the user. If you have not read the research procedure yet, call the instructions tool with command research first.

Input parameters:

- `url` (string, required): The site to test, e.g. https://staging.example.com

### `install_snippet` (~119 tokens)

Get the Usercase script for the connected project, with where to put it per framework. If nothing is connected yet, it opens the browser to connect and says what to tell the user. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked. If you have not read the install procedure yet, call the instructions tool with command install first.

### `save_people` (~175 tokens)

Save virtual users to .usercase/people.json (adds to what is there). People have no names — like real visitors; each gets a number (p1, p2…) to refer to them by. Make people who would really come to this site — varied goals, devices, arrival paths, and states of mind. Do not make everyone a perfect fit for one feature. Show the list to the user before running visits.

Input parameters:

- `people` (array, required)
- `research` (string): Only when the run takes part in a research — its id, as path_tasks shows it: everyone saved in this call takes part in it
- `site` (string, required): Site origin the visits go to
- `site_about` (string, required): One or two English sentences on what the site is, as a visitor would understand it

### `list_people` (~26 tokens)

List the virtual users in .usercase/people.json and whether each has visited yet.

### `results` (~54 tokens)

Recent visit results (one summary per visit) and what the safety guard blocked. Call after each round of visitor sub-agents finishes — it also says whether the research run goes on to another round.

Input parameters:

- `limit` (integer)

### `login` (~306 tokens)

Open a visible browser on the user's screen so THEY can sign in to the site with one demo account. Only the resulting session (cookies) is saved, under an account name in .usercase/sessions/ — the password never passes through you or us. Call it once per demo account, one at a time. Returns immediately; tell the user to sign in and close the window, then run check_site — it checks whether the sign-in really worked. If an account is not signed in or has expired, call login again with that same account name. Members (member=true) are spread across the signed-in accounts. Never ask the user for their password.

Input parameters:

- `account` (string): Account name to save it as (a1, a2 …). Leave out for a new account; give an existing name to sign in again
- `lifetimeHours` (number): How long a sign-in lasts, if the auth code says (e.g. a session maxAge or ttl). Shown as time left, and the account is not used after it
- `url` (string, required): The sign-in page, or any page of the site
- `window` (string): Which window. chrome (default): the user's normal Chrome — Google and other sign-in buttons work, but a sign-in cookie that lasts only until the browser closes is lost. playwright: keeps such cookies…

### `set_writes` (~144 tokens)

Choose whether visitors' writes reach the site: signing up, posting, commenting, saving, liking. 'block' (the default) sends nothing to the site; 'send' lets those through for real. Only the user can decide this — ask them, and only call this with their answer. 'send' suits a test or staging site, or data that may be messed up; on a live site real users will see what visitors post. Payments, deleting, wallet connections and sign-out stay blocked either way. Saved in .usercase/settings.json.

Input parameters:

- `mode` (string, required): block = nothing is sent to the site; send = writes really reach the site

### `connect` (~70 tokens)

Connect Usercase to a project in the browser, or switch to another project. Opens the Usercase dashboard where the user signs in and picks the project. Other tools connect by themselves when nothing is connected — use this only when the user wants another project, or check_site says the SDK sends to a different project.

### `setup` (~69 tokens)

Install the visitor sub-agent definition (Claude Code: ~/.claude/agents/, Codex: ~/.codex/agents/ — user-wide, nothing is added to the repository) so visitors can be started. Run once if that agent type is not available. The user may need to restart Claude Code afterwards.

### `question_context` (~63 tokens)

Screens and element words from this project's recent real visits. Call first in the question procedure, before writing a condition — page globs and click targets must match what visitors actually saw. If you have not read the question procedure yet, call the instructions tool with command question first.

### `question_check` (~50 tokens)

Run a condition over this project's recent visits: how many it matches, grammar problems, overlap with existing questions, and what matched visitors did. Repeat until there are no problems.

Input parameters:

- `condition` (object, required)

### `question_save` (~213 tokens)

Save the question as a DRAFT in the dashboard Inbox, after the user approved it. The server checks the condition again and refuses it if there are problems. Nobody sees it until someone turns it on.

Input parameters:

- `acceptWarnings` (boolean): true only after the user said to save even though it does not match recent visits
- `allowOther` (boolean): Let visitors write their own answer (choice only). Default true
- `answerType` (string)
- `choices` (array): For choice: 2–6 choices, exactly one with noProblem: true
- `condition` (object, required)
- `question` (string, required): English, under 15 words. Asks about this moment
- `title` (string): English, a few words, for the Inbox
- `triggerEn` (string): English. One plain sentence: when and in what situation it appears. No paths or class names
- `why` (string): English. What the team wants to learn, shown in the Inbox

### `steps_brief` (~80 tokens)

What is in the user's Several steps window: whether the card is a question or a research invite, the page under Where, and the words they wrote. Call first in the steps procedure. If you have not read the steps procedure yet, call the instructions tool with command steps first.

Input parameters:

- `session` (string, required): The window id from the dashboard command

### `steps_send` (~125 tokens)

Send the condition back to the user's Several steps window (a question or a research invite), after question_check shows no problems. The server checks it again and refuses it if there are problems. The user saves it there.

Input parameters:

- `acceptWarnings` (boolean): true only after the user said to send it even though it does not match recent visits
- `condition` (object, required)
- `session` (string, required): The window id from the dashboard command
- `triggerEn` (string, required): English. One plain sentence: when and in what situation it appears. No paths or class names

### `report_findings` (~125 tokens)

List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Input parameters:

- `audience` (string): Which report: virtual users (default) or real people
- `research` (string, required): The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)

### `report_finding` (~150 tokens)

Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Input parameters:

- `audience` (string): Which report: virtual users (default) or real people
- `finding` (string, required): Finding key, e.g. F1
- `research` (string, required): The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)

### `report_fix` (~245 tokens)

Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). If the last fix of this finding is already live on the site, this starts the next fix (fix 2, 3 …); otherwise it adds to the current one. The report compares people after each fix goes live with the version right before it.

Input parameters:

- `audience` (string): Which report: virtual users (default) or real people
- `files` (array): Repository paths of the files changed (or to be changed)
- `finding` (string, required): Finding key, e.g. F1
- `prUrl` (string): Pull request link, if one was opened
- `research` (string, required): The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)
- `status` (string, required)
- `summary` (string): One sentence for the team: what visitors now see differently

### `issue_list` (~80 tokens)

List the open issues of the Usercase project (problems found from visitors' answers to questions on the site): id, title, where, whether it is a clear fix, and whether one is being fixed. Use when the fix command has no issue id. If you have not read the fix procedure yet, call the instructions tool with command fix first.

### `issue_read` (~93 tokens)

Read one issue of the Usercase project with all its evidence: the question and page, what people chose, what they wrote, the AI's reading, other issues with the same cause, and earlier fixes. Read it before looking for the code. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Input parameters:

- `issue` (string, required): The issue id, as in the dashboard command

### `issue_fix` (~140 tokens)

Record on a Usercase issue that you are fixing it (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). After a finished fix, starting again records the next fix.

Input parameters:

- `files` (array): Repository paths of the files changed (or to be changed)
- `issue` (string, required): The issue id
- `prUrl` (string): Pull request link, if one was opened
- `status` (string, required)
- `summary` (string): One sentence for the team: what visitors now see differently

### `path_tasks` (~98 tokens)

List the tasks of a Usercase research (from the dashboard) and whether each already has an expected path. Call first in the path procedure. If you have not read the path procedure yet, call the instructions tool with command path first.

Input parameters:

- `research` (string, required): The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)

### `path_start` (~147 tokens)

Open a fresh browser on the page where the task's intended route begins and start recording its expected path. The page itself is step 1. Starting again discards the recording in progress.

Input parameters:

- `account` (string): Demo account saved by login (a1 …) if the route needs a signed-in user
- `device` (string)
- `task` (string, required): Task id from path_tasks · plan-<n> for task n of a research not saved yet (new-research) · draft:<draft>:<index> for a saved draft
- `url` (string, required): Full URL where the route starts — the local dev server is fine; only paths are saved

### `path_click` (~112 tokens)

Click a numbered element from the latest screen. By default it becomes a step of the path (the element is recorded; a new page reached is recorded too). record=false for clicks that are not part of the route (closing a cookie banner) — they are still repeated by path_check. press=false records the element as the final click without pressing it (a Pay or Submit button the safety guard will not press).

Input parameters:

- `index` (integer, required)
- `press` (boolean)
- `record` (boolean)

### `path_type` (~46 tokens)

Type into a numbered field (a search box, a quantity). Not a path step, but repeated by path_check.

Input parameters:

- `index` (integer, required)
- `text` (string, required)

### `path_scroll` (~23 tokens)

Scroll the recording page to see more.

Input parameters:

- `direction` (string)

### `path_pattern` (~85 tokens)

Make a page step match any page of its kind: /notice/6553c3ba → /notice/:id. Use when participants would open a different item than the one you did (the route reads from the code). Applies to every step on that page.

Input parameters:

- `step` (integer, required)
- `url` (string, required): Path pattern with :name for the changing parts

### `path_check` (~54 tokens)

Walk the recorded path again in a fresh browser: every clicked element must still be found at its recorded position with the same text, and every page must be reached. Lists the screenshots to show the user. Required before path_save.

### `path_save` (~107 tokens)

Upload the checked path to the dashboard, replacing the task's expected path. Only after the user approved it. success: keep (default) leaves the task's success condition; page = done on reaching the last page of the path; click = done on the last recorded click. With page or click the saved path ends at that point (later steps are left out: the task ends there, so nobody could reach them). Ask the user before changing it.

Input parameters:

- `success` (string)

### `research_context` (~83 tokens)

What this project's data says is worth researching: open findings, where real visitors and virtual users left, what virtual users said when they left without getting what they came for, and the researches and drafts that already exist. Call first in the new-research procedure. If you have not read the new-research procedure yet, call the instructions tool with command new-research first.

### `research_save` (~311 tokens)

Save the research as a DRAFT in the dashboard Inbox, after the user approved it. It becomes a research only when someone creates it there. Paths are page paths starting with / (no host), with :name for the parts that change. Expected paths recorded and saved beforehand as plan-<n> (n = the task's position in tasks, from 1) are uploaded with it.

Input parameters:

- `basis` (string, required): What the research came from: real visitor data, virtual user data, or neither (the user's question or the code)
- `findingIds` (array): Ids of the findings it answers, from research_context
- `hypotheses` (array): Team only, never shown to participants: what the team expects to go wrong, one per item, 1–3 usually. The report judges each one. Each must be something these tasks can confirm or rule out
- `invite` (object)
- `minutes` (integer): Minutes the whole session takes (tasks and questions). Shown on the invite card and the start screen
- `purpose` (string, required): Shown to participants (invite card and start of the study): one or two sentences, in their words, on what they will help with. Never the team's evidence, suspicions or hypotheses
- `questions` (array): Asked after all tasks
- `start_screen` (object): What participants read before the first task
- `tasks` (array)
- `title` (string, required): Short, for the team

### `open_visit` (~70 tokens)

Start a visit as one virtual user from people.json. Returns a visit_id and what you see first. You ARE this person from now on. If it says the site is blocking us, stop and report that.

Input parameters:

- `person` (string, required): The person's number from people.json, e.g. p3

### `act` (~347 tokens)

Do one thing on the screen, as the person. Numbers refer to the latest screen you were shown — only what is in view; scroll to see more. It happens after the pause a real person would take on that screen, then you get the new screen — or a survey card, or the end of the visit.

Input parameters:

- `action` (string, required)
- `done` (boolean): For leave: true if you got what you came for
- `index` (integer, required): Number of the thing to click, type into, hover over or drag. For scroll/scroll_up, the number of a part of the screen that scrolls on its own (or of something inside it) — or -1 to scroll the page. -…
- `text` (string): For type: what you type (in the language of the site), or the option/value to choose in a dropdown, slider or date box. For press: the key (Escape, Tab, Enter, ArrowDown…). For drag without `to`: the…
- `times` (integer): For scroll, scroll_up, click or press: how many times in a row, quickly (scrolling down while skimming, clicking again because nothing happened, pressing an arrow key a few times). Default 1
- `to` (integer): For drag: the number of the thing to drop it onto; -1 to drag in the direction given in text
- `visit_id` (string, required)
- `why` (string, required): One short sentence in English: what you are doing and why, as this person

### `answer_card` (~156 tokens)

Respond to the survey card on screen, as the person. Decide `bothered` FIRST — most people close these without reading. Only if bothered, pick an option, write your own words, or still close.

Input parameters:

- `action` (string, required)
- `bothered` (boolean, required): Would this person, right now, bother to answer at all?
- `bothered_why` (string, required): English, one sentence
- `choice_index` (integer, required): Option number for choose; -1 otherwise
- `other_text` (string): Your own words for other, in the language of the card, the way this person writes
- `visit_id` (string, required)
- `why` (string, required): English, one sentence: why this answer

### `instructions` (~392 tokens)

Start here for any Usercase work — whether the user typed a command or just asked in their own words. Returns the step-by-step procedure; follow it as the user's request, and call this before the other Usercase tools. Commands: research (test or get feedback on the site with virtual users; `research` id to have them take part in a research), new-research (plan or create a research / usability study), install (add or install the Usercase script on the site), question (make a question to ask visitors at a moment on the site), steps (write the steps for the question open in the dashboard; `session` = its window id), path (record the expected paths of a research's tasks; `research` id, optional `task`), fix (fix a finding from a research report: `research` id + `finding` key like F1, `audience` real for the real-people report; or an issue from Issues: `issue` id), connect (connect this repository to another Usercase project).

Input parameters:

- `audience` (string)
- `command` (string, required)
- `count` (string): How many people (default 5), or "unlimited" to keep going until you stop it
- `finding` (string)
- `focus` (string): Only people who come for this part of the site, e.g. calendar, or comments and sharing
- `issue` (string): An issue id from the dashboard's Issues — fixes that issue instead of a report finding
- `research` (string): The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)
- `session` (string): The window id shown in the dashboard command
- `task` (string)
- `url` (string)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp#diagnostics

## Score history

- 2026-11-21: 64
- 2026-11-20: 63
- 2026-11-19: 63
- 2026-11-18: 62
- 2026-11-17: 62
- 2026-11-16: 61
- 2026-11-15: 61
- 2026-11-14: 45

## Common questions

### What is the Usercase MCP server?

Usercase is an MCP server listed in the public MCP registry as io.usercase/mcp. Ask real users on your site and run virtual users in a real browser, then fix what they hit. This page covers its npm package (@usercase/mcp).

### Is the Usercase MCP server safe to use?

Usercase scores 64 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. It declares no install or post-install scripts. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Usercase MCP server expose?

Usercase exposes 34 tools: check_site, install_snippet, save_people, list_people, results, and 29 more. Their descriptions and schemas cost roughly 4,473 tokens of context every time the server is loaded.

### Is the Usercase MCP server still maintained?

Usercase is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Usercase MCP server under?

Usercase declares the UNLICENSED licence, which is not on the OSI-approved list. Read the terms before using it at work, and note this covers the source only, not the cost of any service it calls.

### What did VerifyMCP test on the Usercase MCP server?

VerifyMCP ran 15 checks on Usercase, covering Malware scan, Known CVEs, Install scripts, Dependency health and 11 more. One item could not be completed, a gap on our side rather than a finding about Usercase: Security disclosure. Endpoint Security and Transport & Reachability do not apply to an npm package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- npm package: https://www.npmjs.com/package/@usercase/mcp
- Socket report: https://socket.dev/npm/package/@usercase/mcp
- Website: https://usercase.io/
- Changelog RSS feed: https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp.json
- HTML version of this page: https://verifymcp.io/servers/io-usercase-mcp/usercase-mcp
