ScreenshotAgent runs a remote Model Context Protocol (MCP) server at https://screenshotagent.com/mcp. Connect your coding agent to it and ask things like “recapture the onboarding screenshots after this deploy”, “give me the embed URL for the settings page” or “find the billing settings screenshot in dark mode”.
1. Create a token
The MCP server uses your team's API tokens. Go to Settings → Team → API tokens and create a token with the scopes the agent needs:
| Scopes | What the agent can do |
|---|---|
| read | Browse projects and screenshots, get embed URLs (read-only) |
| read, captures | Also recapture existing screenshots and add AI annotations |
| read, captures, manage | Also create new screenshots |
Warning
captures only to agents you trust to spend them.2. Connect your agent
Claude Code
claude mcp add --transport http screenshotagent https://screenshotagent.com/mcp \
--header "Authorization: Bearer <your-api-token>"Add --scope user to use it in every project. Run /mcp inside Claude Code to check that it is connected.
Cursor
Add the server to ~/.cursor/mcp.json, then restart Cursor. A project's .cursor/mcp.json works too, but keep tokens out of git.
{
"mcpServers": {
"screenshotagent": {
"url": "https://screenshotagent.com/mcp",
"headers": {
"Authorization": "Bearer <your-api-token>"
}
}
}
}ChatGPT, Claude and other OAuth clients
Apps that sign in with OAuth don't need a token. Add https://screenshotagent.com/mcp as a connector, sign in to ScreenshotAgent when asked and pick the team to connect. Team viewers get read-only access; anyone who can capture also gets captures and manage. See and disconnect apps under Settings → Team → Connected apps.
Other clients
Any client that supports the Streamable HTTP transport can connect. Point it at https://screenshotagent.com/mcp and either sign in with OAuth or send your token in the Authorization: Bearer header on every request. Local (stdio) servers are not supported.
Tools
| Tool | Scope | What it does |
|---|---|---|
| list_projects | read | Projects with base URL, screenshot count and schedule |
| list_screenshots | read | Screenshots filtered by project, tag, status or search, paginated, with embed URLs for public ones |
| search_screenshots | read | Search by meaning and keyword over names, tags, projects, URLs and what is on screen (title, headings, description, UI elements, visible text), best match first, with snippets and embed URLs for public ones |
| get_screenshot | read | Full detail: embed URLs (latest, per variant, pinned version), what was on screen at the latest capture, last capture status or error, recent versions |
| get_capture_status | read or captures | Poll a queued capture; returns the new version and its URLs when ready |
| recapture | captures | Recapture by screenshot ids, tags, project or all; returns queued and skipped counts with reasons |
| create_screenshot | manage + captures | Create a private screenshot from a name, public URL and optional project, viewport, full-page flag and instructions, and queue its first capture |
| annotate_screenshot | captures | Mark up a screenshot (presets such as hand_drawn_circle, add_arrow, add_callout, blur_sensitive, plus instructions naming the target). AI finds the element and the mark is drawn on top; uses one AI annotation |
| get_annotation_status | read or captures | Poll an AI annotation; returns the annotated version and its URLs when done |
| list_waiting_versions | read or manage | Versions waiting for approval, each beside the live version embeds show, with image URLs to compare and the reason a version was held |
| get_version_diff | read or manage | Compare any version with the live one: both image URLs, whether it is live or waiting, and how much changed since the capture before |
| approve_version | manage | Approve a waiting version, revert to an older one, or dismiss a waiting version (action: dismiss). The token creator must be allowed to approve |
| upgrade_plan | manage | Show the current plan and the paid plans, or return a Stripe Checkout link for one. The user pays on that page; nothing is charged until they do. Owners and admins only |
| add_card | manage | During the free trial, show what adding a card unlocks and return a Stripe link where the user adds one, with a disclosure of what is charged and when. Owners and admins only |
Screenshots created over MCP start out private. Make one public in the app to get its permanent embed URLs.
Searching screenshots
Every capture records what was on screen: the page title, final URL, headings, a short description of the layout and notable elements (such as “settings modal with a red Delete button”), labels for visible UI elements (such as “Upgrade button” or “Invoices table”) and the most important visible text. Passwords, API keys and tokens are never stored. search_screenshots searches that alongside each screenshot's name, tags, project and URL, scoped to your team.
{
"query": "billing settings dark", // required, your own words or words from the page
"project_id": 12, // optional
"tag": "onboarding", // optional, exact tag name
"limit": 10 // optional, 1-50
}Search matches by meaning, not just keywords: each document is embedded with a text-embedding model and compared with the query, and those matches are merged with full-text keyword results, so “change password” finds a screen labelled “Update credentials”. Each result has matched_by set to keyword (the snippet highlights matching words in **bold**) or meaning (the snippet is the closest field). Quoted phrases, or and -word exclusions keep their exact keyword meaning. It searches the text and descriptions recorded at capture time, not image pixels. Screenshots captured before search launched match on their name, tags and URL until their next capture. The same search is available over the REST API at GET /api/v1/screenshots/search?q= with a read token.
Limits
The MCP server allows 60 requests per minute per token, counted separately from the REST API's limit. Captures it queues share the API's budget of 100 API-initiated captures per day by default, and also count toward your plan and respect its limits. When a capture can't be queued, the tool returns an error explaining why, and the agent sees it.
Example prompts
- “We just shipped the new billing page. Recapture every screenshot tagged billing.”
- “Find the dashboard screenshot and put its embed URL in docs/getting-started.md.”
- “Which screenshots failed their last capture, and why?”
- “Find the onboarding screenshots and give me their embed URLs.”
- “Circle the new Export button on the reports screenshot for the release notes.”