# MCP reference

`nitpick mcp` starts an MCP server on stdio. Your agent uses it to read feedback and mark it resolved. Nitpick runs no AI itself and needs no model key: your agent uses your own AI subscription.

## Add it to your agent

Claude Code:

```bash
claude mcp add nitpick -- npx -y @nitpickhq/cli mcp
```

Codex:

```bash
codex mcp add nitpick -- npx -y @nitpickhq/cli mcp
```

Cursor, in `.cursor/mcp.json` (or `~/.cursor/mcp.json` for all projects):

```json
{
  "mcpServers": {
    "nitpick": { "command": "npx", "args": ["-y", "@nitpickhq/cli", "mcp"] }
  }
}
```

The server reads your login from `~/.config/nitpick/config.json`, or `NITPICK_TOKEN` from the environment. Run `npx -y @nitpickhq/cli@latest login` first: it opens the browser, where you create an account, start the subscription and press Allow.

## Tools

| Tool | What it does |
|---|---|
| `list_apps` | Your apps, with open counts and how many are locked. |
| `list_feedback` | Reports, newest first. Filters: app, status, kind, screen, element, app version, platform, since, limit. |
| `get_feedback` | One report as text, plus the screenshot as an image with the tap position and the element box drawn on it. |
| `resolve_feedback` | Mark a report resolved. |
| `reopen_feedback` | Mark a report open again. |
| `feedback_stats` | Open counts by screen, by element and by app version. |
| `get_app_settings` | Which kinds of feedback are on and the texts per language, for one app. |
| `update_app_settings` | Turn the kinds on or off and set or remove the texts per language (`footer`, `thanks`). Gives the old and new value of each change. |
| `create_app` | Create an app on your account and return its id and public key. |

Tokens are not available over MCP. Look at them and revoke them in the dashboard or with `nitpick tokens list` and `nitpick tokens revoke`.

## Do not pre-approve the tools that change things

Most agents let you approve tools once and for all. Do that for the tools that only read (`list_apps`, `list_feedback`, `get_feedback`, `feedback_stats`, `get_app_settings`), if you like. Do not put `update_app_settings` and `create_app` on a list of tools that are allowed in advance. Reports are written by anonymous people, and a report could try to talk your agent into changing your settings. Keep the approval step for these two: you see the change before it happens. The tool descriptions tell the agent to change settings only when you ask, but that is not a safeguard. The approval is.

`update_app_settings` takes `app_id`, optional `general` and `specific` (booleans), and optional `texts`: a list of `{language, key, text}`, where `key` is `footer` or `thanks` and `text` is a string or null to remove it. Each language and key may appear once. The settings reach your users within a minute, the next time the app starts or comes back after more than an hour in the background. See [Settings](/docs/settings).

## The subscription in the output

- In the states `grace`, `locked` and `inactive`, the text of `list_apps` and `list_feedback` starts with one line about the subscription and the renew address, for example "Nitpick: the subscription has ended; new reports are locked (3 reports locked now)." Nothing is written to the output of the server itself.
- From 80% of the monthly limit of 2,000 reports a second line says how many are used.
- `list_apps`, `list_feedback` and `feedback_stats` mention how many reports are locked, when that is more than 0. Locked reports are never shown.
- A locked report answers "This report is locked until the subscription is renewed: <address>". Tell the user to renew; do not try again.
- Creating an app above 50 apps (409 `limit_reached`) gives a message that names what the user can clean up. Creating an app without a running subscription (402) says that an active subscription is needed.

See [Billing and limits](/docs/billing).

## A typical loop

1. The agent calls `list_feedback` with `status: open`.
2. For a promising report it calls `get_feedback` and looks at the screenshot.
3. It finds the code through the `screen` and `element` names, and makes the change.
4. It calls `resolve_feedback` with the report id.