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 server options: the hosted one at https://mcp.peekr.dev/mcp, and a local one inside the Mac app that reads the last synced library. Keep the Mac app running and check sync status; shared mutations require a connection.
Start with a setup prompt
Open your workspace → Connect an agent → Copy setup prompt. Paste it into your agent and approve access in the browser. One personal connection can cover all your accessible workspaces. The agent chooses a workspace for each task and verifies setup by opening a real issue. Restricted connections remain available. If your client cannot configure itself, it explains the settings step or restart needed.
The Peekr guide is included
Both servers include the Peekr workflow through get_peekr_guide, the peekr://guide resource and the peekr prompt. Your agent can read it after connecting. Installing an MCP connection does not write skill files into your client. If your agent supports automatic skill discovery, the optional Peekr skill ZIP and installation prompt are also available. You can read the instructions before installing.
Settings, groups and invitations
Ask your agent to create a group, preview who an invitation will include, invite someone to selected groups, or change your settings. Hosted connections need the optional Manage settings and invitations permission for settings and sharing. Enable it when connecting or under Account → Connected apps. For tokens, create a new token with this permission. Existing connections keep their original access.
The workspace role and connection restrictions still apply. A member cannot become an admin through their agent. Account name and notification preferences require all-workspace management access. The local Mac server uses the signed-in app session and preserves its configured workspace restriction. Passwords, billing, deletion and ownership transfer remain in the app.
Manual setup: 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, create a personal token under Connect an agent → Manual setup and access tokens, or in your account. 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.
On Windows
Peekr for Windows is in progress. Everything below describes how it works; it ships when it is signed and tested on real machines. Until then Windows runs Peekr in the browser — the same board, the same agents, nothing to install. Downloads
The same server, started from Peekr's own runtime, so there is nothing else to install — no separate Node. Settings → Agent gives you the setup prompt and, under Other ways to connect, the exact configuration for Codex, Claude Code, Cursor, VS Code, Claude Desktop and Windsurf. By hand it is a command, its script and one environment variable:
claude mcp add --scope user peekr --env ELECTRON_RUN_AS_NODE=1 -- ^ "%LOCALAPPDATA%\Programs\Peekr\Peekr.exe" ^ "%LOCALAPPDATA%\Programs\Peekr\resources\peekr-mcp.cjs"
The environment variable is not optional and Peekr.exe --mcp is not an alternative: the application executable is a Chromium process, and on Windows it writes a byte to its own output before any of Peekr's code runs, which breaks the protocol on the first message. Peekr refuses that invocation and tells you the right one rather than appearing to work.
Reading the board works whether or not Peekr is open — every answer says how fresh that copy is and whether anything is waiting or stuck. Changing shared work is different: claiming an issue, resolving it, commenting or inviting somebody is the server's decision, so Peekr has to be running to carry it and confirm it. With Peekr closed your agent is told exactly that, and nothing is changed. A capture that lives only on that PC is changed there, and says so.
The tools
| Tool | What it does |
|---|---|
list_workspaces | The workspaces your connection can access. Choose one explicitly for each task. |
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 | Reserve a capture before working. An active claim cannot be silently overwritten; keep the returned claim token for completion. |
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 and an overview of their open work. Use list_workspace_members for people and get_workspace_settings for editable group IDs and versions. |
capture_stats | Counts by status, and where the open work is. |
get_peekr_guide | The built-in Peekr skill, available without a separate installation. |
get_account_settings | Your display name and notification preferences. Requires account-wide management access. |
update_account_settings | Change your display name or selected notification preferences. |
get_workspace_settings | Current workspace settings, group IDs, versions and audiences. |
update_workspace_settings | Workspace name, new-group sharing default and agent resolution review. |
list_workspace_members | Current teammates, guests and roles. |
create_group | Create a group using the workspace default audience, or choose private explicitly. |
update_group | Change a group's name, color, audience or default assignee using its current version. |
preview_invitation | Show the groups and role an invitation will grant, without sending anything. |
create_invitation | Invite a requested recipient, or create a one-person link. Guests can be invited to several groups. |
list_invitations | Pending invitations, original group access, expiry and email delivery status. |
revoke_invitation | Stop a pending invitation. People who already joined keep their membership. |
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.
Include the workspace name if you belong to more than one. A triage request asks for analysis; it does not authorize editing code, sending invitations or changing sharing.
Example management requests
- “In the Website workspace, create a group called Checkout feedback, shared with the team.”
- “Show what a guest invited to Design and Feedback would see. Don't send an invitation yet.”
- “Invite the email I gave you as a guest to those two groups.”
- “Turn off my comment email notifications and keep in-app notifications on.”
If an action says management permission is missing, enable that permission in Account or replace the token. After updating the Mac app, restart the local MCP connection or agent session so it discovers the new tools. Local reads can be stale until sync completes; use the sync recovery guide if web and Mac disagree.