# The screenshot MCP server

ScreenshotBuddy speaks the Model Context Protocol at `https://screenshotbuddy.io/mcp`, so the AI client you already work in can render a page to an image or a PDF itself instead of being told how to write the HTTP request. An agent that can see a page stops describing what it thinks it built: it captures the thing, looks at the capture, and notices the header it pushed off the screen before you do.

Connecting a client mints no second credential and grants no second allowance. The tokens are the ones you already have, and what a render costs is counted in the same place it is counted for an HTTP call.

## Connecting a client

A client needs two things from you: the URL above, over streamable HTTP, and an `Authorization` header carrying an API token, the same header a REST call sends. There is no OAuth step and nothing to install. Everything below is filled in except the key, which goes where it says `<your API key>`.

Claude Code:

```bash
claude mcp add --transport http screenshotbuddy https://screenshotbuddy.io/mcp --header "Authorization: Bearer <your API key>"
```

Run it in the project you want the server available in. Claude Code keeps the header with the server, so the token travels on every call and never has to be repeated.

Claude Desktop and Cursor:

```json
{
    "mcpServers": {
        "screenshotbuddy": {
            "url": "https://screenshotbuddy.io/mcp",
            "headers": {
                "Authorization": "Bearer <your API key>"
            }
        }
    }
}
```

Cursor reads `.cursor/mcp.json` in a project and `~/.cursor/mcp.json` everywhere. Claude Desktop takes the same pair of values wherever it keeps its MCP servers, as does any other client that can add a remote one: if you can give it a URL and a header, you can connect it.

VS Code, in `.vscode/mcp.json`:

```json
{
    "servers": {
        "screenshotbuddy": {
            "type": "http",
            "url": "https://screenshotbuddy.io/mcp",
            "headers": {
                "Authorization": "Bearer <your API key>"
            }
        }
    }
}
```

That one works for GitHub Copilot in agent mode. Commit the file and everyone on the repository gets the server, though not the key.

Whatever the client, commit the URL and not the token. The file that names the server is a file people share; the token is a credential that spends your credits. You create tokens under [Settings, API tokens](https://screenshotbuddy.io/settings/api-tokens), and there is deliberately no endpoint that mints one, so an agent cannot sign itself up. A token can be narrowed to screenshots only or to PDFs only, which is worth doing before handing it to something that runs unattended.

## The five tools

The server exposes five, described well enough that a model picks the right one without being told. Two of them render a page each, one reports where the account stands before anything is spent, and two carry a whole list at once: submit a batch, then poll it.

| Tool | What it answers with |
| --- | --- |
| `take-screenshot` | The image itself, in the conversation, so the model can look at what it captured rather than read a description of it. Beside it comes a line naming the URL, the size and the format, and saying what the render cost. When the target answered something other than a 2xx, a login wall or a 404 that renders perfectly well, the tool says so in words at the end of that line. |
| `create-pdf` | A link to the rendering rather than the file itself, because a PDF is far too large to travel in a tool result. The page is rendered on the call, so a failure surfaces to the agent that can act on it rather than to whoever clicks the link later. The link is an ordinary [signed URL](https://screenshotbuddy.io/documentation/signed-urls.md), needs no token, and works for at most 24 hours, less when the cached copy behind it lapses first. |
| `check-usage` | Credits remaining, the plan, when the period resets and both per-minute limits. It answers zero rather than refusing when the account has nothing left, which is the case it exists for: an agent that can read the number can stop, say so, and pick the work back up after the reset. |
| `submit-render-batch` | The batch that will carry a queued list of renders, answered immediately with its id, every item still queued. Nothing renders on the call and nothing is billed by it: each item is rendered in the background and billed as it would have been one at a time, under the [batch rules](https://screenshotbuddy.io/documentation/batch-renders.md). |
| `check-render-batch` | Where a submitted batch has got to, with a signed URL for every finished item and the machine readable reason for every failure. Polling is free the way `check-usage` is free, so poll a few seconds apart until the batch reports itself finished. |

A refusal comes back as the error a REST caller would have received, carrying the same machine readable `code` from the same published set, so a model can tell a permission it will never have from a timeout worth one more try.

One page you need now goes to the rendering tools, which answer with the rendering itself; a list goes to the batch pair, which trades the wait for an id to poll.

## The agent skill, if MCP is not the fit

For a client that reads Agent Skills rather than MCP servers, there is a skill instead. One command, no server to configure:

```bash
npx skills add screenshotbuddy.io
```

It installs a skill that teaches the agent to write the HTTP calls itself.

The honest way to choose between them: the MCP server is for the agent taking the screenshot, and the skill is for the agent writing the code that will take screenshots later. If you want a capture back in the conversation right now, so the model can look at it, connect the server. If the agent is building your integration and the requests will run in your application long after the chat is closed, the skill is the better fit, because what it leaves behind is code that calls the API directly rather than a dependency on a protocol your production job does not speak. Nothing stops you having both, and they authenticate with the same tokens.

## What it costs when an agent loops

An agent iterating on a layout will capture the same page again and again, so the interesting question is not what one render costs but what the fifth identical one does. One credit per fresh render, exactly as over HTTP. An identical call repeated is answered from your [cache](https://screenshotbuddy.io/documentation/caching.md) and costs nothing, a failed render is refunded, and `check-usage` is free whatever it reports. Both rendering tools say which of the two happened in the line beside their answer, so a model can tell a paid render from a free one and has a reason to reach for the cache rather than burn through the month.

The per-minute limits split the same way, and they are counted in the flow both surfaces share rather than per surface, so a client gets no second allowance by asking over MCP instead of over HTTP. A fresh render spends the render budget your plan sets; an answer served from the cache comes out of a separate and far larger budget. The transport carries a ceiling of its own, set at the sum of those two, for the calls that never reach a render at all: the protocol handshake, the tool listing, `check-usage`. An agent polling and re-reading cannot throttle the work you were saving the renders for.

How many renders and how many per minute is what the plans differ on, and the free plan is enough to find out whether this is useful before anything is paid for. See [pricing](https://screenshotbuddy.io/pricing) and [how the two budgets work](https://screenshotbuddy.io/documentation/rate-limits.md).

## Why the first call usually works

Most integration friction with an agent is not the protocol, it is the guessing: a parameter that does not exist, a value outside the range, a retry on an error no retry fixes. So the descriptions are machine readable everywhere an agent might look. `take-screenshot` and `create-pdf` take their parameters from the same description of the API their REST counterparts use, and each one publishes the exact range its own mode allows rather than the wider of the two, because the tool is the mode and there is no `pdf` switch to get wrong.

- [llms.txt](https://screenshotbuddy.io/llms.txt) is an index of every documentation page, in markdown, with a line on what each one covers.
- [llms-full.txt](https://screenshotbuddy.io/llms-full.txt) is the same documentation as one document, for a reader that would rather fetch once than ten times.
- The [OpenAPI 3.1 document](https://api.screenshotbuddy.io/v1/openapi.json) carries every parameter, response and error code of the REST API, machine readable.
- The [Agent Skills index](https://screenshotbuddy.io/.well-known/skills/index.json) is discovery for the skill that `npx skills add screenshotbuddy.io` installs.
- Every documentation and use-case page is also served as plain markdown at its own URL with `.md` on the end. This page lives at [https://screenshotbuddy.io/mcp-server.md](https://screenshotbuddy.io/mcp-server.md).

## Where to go next

The [MCP server documentation](https://screenshotbuddy.io/documentation/mcp-server.md) is the full reference: what each tool answers with, how a token's permissions narrow them, and what happens when the page you asked for is not the page that answered. The [agents page](https://screenshotbuddy.io/agents) covers the wider picture, including the plain HTTP route for an agent that speaks neither MCP nor skills. And the only thing you have to fill in comes from an account, so [create one](https://screenshotbuddy.io/register) and hand your agent a token.