# MCP server

> Connect Claude, Cursor, VS Code and other MCP clients to shotkit to take screenshots and read pages as Markdown.

shotkit runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server at `https://shotkit.net/mcp`. Add it to your MCP client with your access key, and your agent can screenshot pages and read them as Markdown. There's nothing to install.

## Tools

| Tool | What it does |
|---|---|
| `screenshot` | Renders a URL, HTML or Markdown and returns the screenshot as an image the model can see, plus its URL. PDF, GIF and video come back as a link. Takes the same options as the API, apart from async, webhook and vision options. |
| `page_to_markdown` | Loads a URL in a real browser and returns its content as Markdown. `selector` narrows it to the part that matters. |

Tool calls count as API requests: they use your plan's [rate limit and monthly screenshots](https://shotkit.net/docs/limits.md), and [cached](https://shotkit.net/docs/caching.md) results are free. If your workspace requires [signed requests](https://shotkit.net/docs/authentication.md#require-signed-requests), MCP calls are rejected, because they can't be signed.

## Authentication

Send your access key from the [API keys page](https://shotkit.net/keys) in the `Authorization` header:

```text
Authorization: Bearer YOUR_ACCESS_KEY
```

`X-Access-Key: YOUR_ACCESS_KEY` works as well. For clients that can't set headers, put it in the server URL: `https://shotkit.net/mcp?access_key=YOUR_ACCESS_KEY`. Keep that URL private, since it contains the key.

## Claude Code

```bash
claude mcp add --transport http shotkit https://shotkit.net/mcp --header "Authorization: Bearer YOUR_ACCESS_KEY"
```

## Cursor

In `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "shotkit": {
      "url": "https://shotkit.net/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}
```

## VS Code

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "shotkit": {
      "type": "http",
      "url": "https://shotkit.net/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}
```

## Clients that only run local servers

For clients that only start local (stdio) servers, such as Claude Desktop's config file, bridge to the remote server with `mcp-remote`:

```json
{
  "mcpServers": {
    "shotkit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://shotkit.net/mcp", "--header", "Authorization: Bearer YOUR_ACCESS_KEY"]
    }
  }
}
```

## Tips for agents

- Ask for `block_cookie_banners` and `block_ads` to get clean captures.
- Keep screenshots small enough for the model: format `jpg` with `image_width` around 1024. Full-page captures of long pages can be too tall for some clients, so cap them with `full_page_max_height`.
- Use `page_to_markdown` to read a page's text, and `screenshot` to check how it looks. See [AI agents](https://shotkit.net/docs/ai-agents.md) for more patterns.