# @usejot/mcp

Let your AI coding agent read and resolve [Jot](https://usejot.co) feedback.

Jot is click-to-pin feedback for live web apps. A reviewer clicks the broken thing on the real page
and types one sentence. Each report comes with a screenshot, the element's selector, the URL, the
browser and OS, and sometimes a session replay with console and network.

This is an [MCP](https://modelcontextprotocol.io) server. It gives an agent such as Claude Code,
Cursor or Windsurf five tools: list feedback, read a report in full, mark it in progress or
resolved, and reply in the thread. Agents can never approve a fix. Only the person who reported
the problem can confirm it is fixed.

## Quick start

### 1. Create a token

In Jot, open **Settings → Agents**, choose the project, name the token after who will use it (for
example "Claude Code") and create it. Copy it straight away: it is shown only once. A token sees
one project and nothing else. You can revoke it at any time on the same page.

### 2. Add Jot to your agent

The server runs with `npx`, so there is nothing to install.

**Claude Code**: run this in your project:

```sh
claude mcp add jot --env JOT_API_TOKEN=jot_agent_… -- npx -y @usejot/mcp
```

Or save this as `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "jot": {
      "command": "npx",
      "args": ["-y", "@usejot/mcp"],
      "env": { "JOT_API_TOKEN": "jot_agent_…" }
    }
  }
}
```

**Cursor**: add the same `mcpServers` block to `~/.cursor/mcp.json` (all projects) or
`.cursor/mcp.json` (one project).

**Windsurf**: add the same `mcpServers` block to `~/.codeium/windsurf/mcp_config.json`.

Any other MCP client works too. Run `npx -y @usejot/mcp` over stdio with `JOT_API_TOKEN` set.

Don't commit a file that contains your token. Add it to `.gitignore`, or keep the token in your
environment.

### 3. Ask

> Fetch the open feedback for this project. Fix what you can, reply on each Jot with what you
> changed, and mark them resolved.

## Settings

| Variable          | Required | Default                 | What it does                                                |
| ----------------- | -------- | ----------------------- | ----------------------------------------------------------- |
| `JOT_API_TOKEN`   | yes      | none                    | Your agent token, from **Settings → Agents**                |
| `BACKEND_API_URL` | no       | `https://api.usejot.co` | The Jot API to talk to. Change it only if you self-host Jot |

The server needs Node 18 or later.

## Tools

| Tool                | Title                         | Takes                                                           | Does                                                                                             |
| ------------------- | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `fetch_feedback`    | List feedback                 | `projectId`, optional `status`, `page`, `environment`, `source` | Lists reports: id, status, source, labels, the reviewer's sentence and where it was left         |
| `get_comment`       | Read a Jot                    | `commentId`                                                     | Everything about one report: the repro context, the thread, and any recording as a text timeline |
| `update_status`     | Set status                    | `commentId`, `status` (`IN_PROGRESS` or `RESOLVED`)             | Moves a report along                                                                             |
| `post_reply`        | Reply in thread               | `commentId`, `message` (up to 5,000 characters)                 | Adds a note the reporter can see, such as "Fixed in PR #204"                                     |
| `create_batch_note` | Post one note to several Jots | `comment_ids` (1 to 50), `message`                              | One note linked across several threads. All or nothing: one unknown id and nothing posts         |

Good to know:

- **Read-only tools.** `fetch_feedback` and `get_comment` are marked read-only, so your client can
  allow them without asking. No tool is destructive. `update_status` is safe to repeat.
- **No approving.** `update_status` accepts only `IN_PROGRESS` and `RESOLVED`. `RESOLVED` means
  "please check", not "closed". The reporter approves.
- **Public feedback is opt-in.** Without `source`, `fetch_feedback` leaves out anonymous visitor
  feedback that the team hasn't triaged. Pass `source: ["PUBLIC"]` to include it.
- **Recordings as text.** An agent can't watch a video, so `get_comment` turns a recording into a
  timeline: console errors and failed requests, each with its timestamp.
- **Structured output.** `fetch_feedback`, `update_status` and `create_batch_note` also return
  structured data next to the text.
- **Errors don't crash.** A failed call comes back as a tool error your agent can read.

## A typical session

```text
You:   Fix the open Jot feedback on the checkout page.

Agent: → fetch_feedback { projectId: "…", status: "OPEN", page: "https://shop.example.com/checkout" }
         3 open reports, two about the same button.
       → get_comment { commentId: "…" }
         "Pay button does nothing on Safari" · button#pay · Safari 18 / macOS
         Timeline: TypeError at 00:04, POST /checkout failed (500)
       → update_status { commentId: "…", status: "IN_PROGRESS" }
       … edits the code, opens PR #204 …
       → update_status × 2 { status: "RESOLVED" }
       → create_batch_note { comment_ids: ["…", "…"], message: "Fixed in PR #204. Please check." }

You:   (the reviewers see the note on their pins, check the fix, and approve)
```

`fetch_feedback` needs the id of the project your token was created for. It is the id in the
address bar when you open the project in Jot. Tell your agent once, for example in your
project's agent instructions file.

## Develop

```sh
git clone https://github.com/usejot/jot-mcp.git
cd jot-mcp
npm install
npm run build
npm test
```

Try it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```sh
JOT_API_TOKEN=jot_agent_… npx @modelcontextprotocol/inspector node dist/index.js
```

This server follows the [Jot SDK contract](https://github.com/usejot/jot-contract) (§5, MCP
tools). A pinned copy ships in `contract/`, and the tests check the tools against its vectors.

## Contributing

Read [CONTRIBUTING.md](./CONTRIBUTING.md). Found a security problem? Don't open an issue. Follow
[SECURITY.md](./SECURITY.md). Everyone taking part agrees to the
[Code of Conduct](./CODE_OF_CONDUCT.md).

## Links

- Website: <https://usejot.co>
- Docs: <https://docs.usejot.co>
- Contract: <https://github.com/usejot/jot-contract>
- JavaScript SDKs: <https://github.com/usejot/jot-js>

## License

[MIT](./LICENSE)