Connect an agent

Peekr speaks MCP — the Model Context Protocol — so any client that supports it can read the board and act on it. There are two servers with the same tools: the hosted one at https://mcp.peekr.dev/mcp, and a local one inside the desktop apps that reads your synced library with no network on the request path.

Hosted: sign in once

The hosted server uses OAuth. The client opens your browser, you sign in and approve, and it's connected — no tokens to paste. It is named peekr-cloud below so it can sit next to the desktop app's local server, which is peekr. It sees exactly what you see (the visibility rule), and on the board its actions read “Claude Code · You”.

Claude Code

claude mcp add --scope user --transport http peekr-cloud https://mcp.peekr.dev/mcp

Claude (desktop and web)

Settings → Connectors → Add custom connector → https://mcp.peekr.dev/mcp.

Cursor

// ~/.cursor/mcp.json
{ "mcpServers": { "peekr-cloud": { "url": "https://mcp.peekr.dev/mcp" } } }

VS Code

// .vscode/mcp.json
{ "servers": { "peekr-cloud": { "type": "http", "url": "https://mcp.peekr.dev/mcp" } } }

Codex

codex mcp add --url https://mcp.peekr.dev/mcp peekr-cloud

Windsurf

// ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "peekr-cloud": { "serverUrl": "https://mcp.peekr.dev/mcp" } } }

On the consent screen you can leave out Act on your behalf to make the connection read-only. Revoke it any time from your account page.

Hosted: with a token

For clients that can't open a browser — CI, scripts, a bot — create a token on the Agents page and send it as a bearer header:

claude mcp add --scope user --transport http peekr-cloud https://mcp.peekr.dev/mcp \
  --header "Authorization: Bearer pk_mcp_…"

Personal tokens act as you and can be limited to read-only or to specific groups. Bot tokens (pk_bot_…, from Settings → Bots) act as the bot — its own identity, its own memberships. Use a bot when the agent runs unattended; see the agent loop.

Local: inside the app

The desktop app's MCP server reads the library on disk — everything you can see, already synced — over stdio. Settings → Agent hands you an instruction to paste into any agent that can run a command: it sets itself up and reports back. That is the whole setup for Claude Code and Codex, which own their own config and would otherwise save over an edit made behind their back. For Claude Desktop, Cursor and VS Code, which have no such command, Peekr writes the config itself — merging one key, keeping a backup.

By hand it is one line:

claude mcp add --scope user peekr --env PEEKR_AGENT=claude-code -- "/Applications/Peekr.app/Contents/MacOS/peekr-mcp"

codex mcp add --env PEEKR_AGENT=codex peekr -- "/Applications/Peekr.app/Contents/MacOS/peekr-mcp"

Upgrading from Dashly? Remove the entry under the old name — it points at a binary that no longer exists, and your agent reports it broken at every start: claude mcp remove --scope user dashly, codex mcp remove dashly.

The tools

Tool	What it does
`list_captures`	One line per capture: note, where it was seen, tags, status, assignee. Filter by workspace, group, status, assignee, text.
`get_capture`	Everything about one or more captures — every screenshot with the user's markup burned in, delivered as images — plus note, context, comments and history.
`claim_capture`	Take a capture before working on it. Assigns it to the caller if unassigned, moves it to in progress.
`comment_on_capture`	Add a diagnosis, a question, or what changed.
`resolve_capture`	Mark it fixed with a commit sha, PR link or explanation. In workspaces set to “propose”, this proposes and a person confirms.
`reopen_capture`	Back to open, when a fix didn't hold.
`update_capture`	Rewrite the note, change priority or status, move to a group (created if missing), set tags, assign.
`assign_capture`	Assign to a person or bot, or unassign.
`create_capture`	File a new issue — with screenshots (base64) or text-only. For agents that find bugs while testing.
`list_groups`	Groups with open/total counts and who's in them.
`capture_stats`	Counts by status, and where the open work is.

Captures are addressed by short ids like #a1c3f2e0 (the last 8 characters of the full id), which is what list_captures prints and what people say out loud.

A good first prompt

What's open in Peekr for the checkout group? Look at the first one — the screenshot, not just the note — and tell me what you think the root cause is before touching anything.

Agents that look at the image before reasoning do noticeably better; the tool descriptions say so too.