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 sees exactly what you see (the visibility rule), and on the board its actions read “Claude Code · You”.
Claude Code
claude mcp add --transport http peekr 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": { "url": "https://mcp.peekr.dev/mcp" } } }VS Code
// .vscode/mcp.json
{ "servers": { "peekr": { "type": "http", "url": "https://mcp.peekr.dev/mcp" } } }Windsurf
// ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "peekr": { "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 --transport http peekr 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 writes the config for Claude Code, Claude Desktop, Cursor or VS Code with one click. Actions taken through it sync up like any other change, attributed to “Client · You”.
claude mcp add peekr -- "/Applications/Peekr.app/Contents/MacOS/peekr-mcp"
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.