> ## Documentation Index
> Fetch the complete documentation index at: https://scrinly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote MCP server

> Connect AI agents to Scrinly's screenshot, comparison, job-status, and usage tools.

Scrinly's remote Model Context Protocol server lets an AI agent capture, inspect, and compare webpages without learning the REST API. The production beta is available at:

```text theme={null}
https://mcp.scrinly.com/mcp
```

The MCP server is a narrow gateway to the same screenshot platform documented here. Rendering, validation, billing, storage, queues, caching, and Visual Style Guide generation remain owned by the Scrinly API.

<Note>
  OAuth is the recommended connection method for interactive clients. You sign in to Scrinly in the browser and approve a bounded set of permissions; the MCP client never receives your Scrinly API key.
</Note>

## Available tools

| Tool                  | What it does                                                                                        | Maximum charge |
| --------------------- | --------------------------------------------------------------------------------------------------- | -------------: |
| `capture_screenshot`  | Captures and stores one screenshot, with optional design evidence, regions, or a Visual Style Guide |    1–7 credits |
| `compare_screenshots` | Compares two stored screenshots with pixel or perceptual analysis                                   |       1 credit |
| `get_job_status`      | Polls an account-owned asynchronous screenshot or diff job                                          |           Free |
| `get_usage`           | Reads the authenticated account's plan and credit allowance                                         |           Free |

Tool discovery and authentication do not consume credits.

## Connect with OAuth

Scrinly publishes OAuth discovery metadata at the MCP origin and supports authorization code flow with S256 PKCE. During authorization, Scrinly shows the client and requested permissions before you approve access.

| Scope               | Allows                                         |
| ------------------- | ---------------------------------------------- |
| `screenshots:write` | Capture stored screenshots and poll their jobs |
| `diffs:write`       | Compare stored screenshots and poll their jobs |
| `usage:read`        | Read the connected account's credit allowance  |

OAuth access is account-scoped and can be revoked without rotating a Scrinly API key. The MCP server still enforces `maxCredits` on every billable tool call.

### Codex CLI and IDE extension

Register the Streamable HTTP endpoint, then complete browser authorization:

```bash theme={null}
codex mcp add scrinly \
  --url https://mcp.scrinly.com/mcp
```

Codex normally starts the discovered OAuth flow immediately. If authorization was skipped or needs to be repeated, run `codex mcp login scrinly`. Do not add an `Authorization` header or an explicit OAuth resource. Codex discovers both the authorization server and protected resource from Scrinly's metadata. Verify the connection with `codex mcp get scrinly` or open `/mcp` inside Codex.

Codex CLI and the Codex IDE extension share MCP configuration on the same host. Once authorization succeeds in the CLI, the connected server is available to the extension after it refreshes its MCP configuration.

See the official [Codex MCP documentation](https://developers.openai.com/codex/mcp/) for client configuration and OAuth support.

### Claude Code

Register the HTTP server at user scope, then complete browser authorization:

```bash theme={null}
claude mcp add --transport http --scope user \
  scrinly https://mcp.scrinly.com/mcp

claude mcp login scrinly
```

Use `/mcp` to confirm the connection. For an SSH or headless session, run `claude mcp login --no-browser scrinly` and follow the printed instructions. Do not configure an `Authorization` header when using OAuth.

See the official [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for scopes and configuration locations.

## Connect with a Scrinly API key

MCP clients without OAuth support and non-interactive services may authenticate with a Scrinly API key. Create the key in the [Scrinly dashboard](https://app.scrinly.com), keep it in the client process's environment or secret manager, and send it only as the MCP transport's bearer credential.

<Warning>
  Never put a Scrinly API key in tool arguments, URLs, repositories, frontend code, or chat messages. Prefer a client feature that reads the bearer token from an environment variable instead of storing the literal key in configuration.
</Warning>

### Codex with an API key

```bash theme={null}
codex mcp add scrinly-service \
  --url https://mcp.scrinly.com/mcp \
  --bearer-token-env-var SCRINLY_API_KEY
```

The `SCRINLY_API_KEY` variable must be available to the process that launches Codex. Restart an already-open IDE after changing its launch environment.

### Claude Code with an API key

Claude Code can expand an environment variable in `.mcp.json`, keeping the literal key outside the project file:

```json theme={null}
{
  "mcpServers": {
    "scrinly": {
      "type": "http",
      "url": "https://mcp.scrinly.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SCRINLY_API_KEY}"
      }
    }
  }
}
```

Launch Claude Code or its VS Code extension from an environment containing `SCRINLY_API_KEY`, then use `/mcp` to confirm the connection.

### Other MCP clients

Configure a Streamable HTTP server at `https://mcp.scrinly.com/mcp` and set its transport header to `Authorization: Bearer $SCRINLY_API_KEY`. Configuration syntax varies by client; use its environment-variable or secret-reference mechanism whenever available. The API key is a transport credential and must never appear inside a tool's input schema.

See [Authentication](/docs/getting-started/authentication) for API-key storage, rotation, and revocation guidance.

## Verify without spending credits

Ask the connected agent:

```text theme={null}
Use Scrinly get_usage. Do not capture anything.
```

A successful response reports the plan, allowance, usage, remaining credits, and active state. It does not expose the account identifier or email.

## Capture a screenshot

Every billable tool requires an MCP-only `maxCredits` ceiling. The server checks the requested feature combination before it calls a billable API route.

```text theme={null}
Use Scrinly capture_screenshot for https://example.com with maxCredits 1.
Do not enable regions, design evidence, or a Visual Style Guide.
```

The default call is synchronous from the agent's perspective: Scrinly submits one durable core job and waits up to 45 seconds. If the work is still running, the result contains a `jobId` and `pollAfterMs`. Poll that job with `get_job_status`; do not submit another capture.

Stored images and region crops are returned as direct B2 resource links with their content type, dimensions, byte size, and SHA-256 where available. The MCP server never downloads, proxies, or embeds the image bytes.

## Spend guard

Use the exact maximum for the evidence requested:

| Evidence                                                | `maxCredits` |
| ------------------------------------------------------- | -----------: |
| Screenshot                                              |            1 |
| Screenshot and raw design evidence                      |            2 |
| Screenshot and regions                                  |            3 |
| Screenshot, regions, and raw design evidence            |            4 |
| Screenshot and Visual Style Guide                       |            6 |
| Screenshot, Visual Style Guide, and raw design evidence |            7 |

A Visual Style Guide already implies regions. The guard uses the maximum generation price even when a cache hit may later reduce the net charge. A rejected ceiling costs zero credits. Always use the returned `charged`, `refunded`, and `net` values as the final settlement.

## Compare screenshots

Keep each stored screenshot's `media` object paired with its own `regions-v1` manifest, then ask the agent:

```text theme={null}
Compare these before and after Scrinly captures using perceptual mode,
overlay visualization, and maxCredits 1. Use their matching region manifests.
```

`compare_screenshots` supports `pixel` and `perceptual` modes plus `overlay`, `heatmap`, `mask`, and `none` visualizations. When both manifests validate, Scrinly compares corresponding regions independently. The result includes similarity, changed pixels, consolidated bounds, region results, and the direct visualization link.

## Safety boundary

The MCP tools intentionally exclude:

* Page headers, cookies, click actions, and authenticated-page automation.
* OpenAI bring-your-own keys.
* Customer B2, S3, or R2 credentials and overrides.
* Webhook URLs and secrets.
* Provider, model, endpoint, and internal-route overrides.

Screenshot targets must be publicly accessible pages accepted by Scrinly's URL policy. Diff inputs must be publicly fetchable HTTPS JPEG or PNG assets. Monitoring tools and private-source credentials remain outside the four-tool MCP surface.

For repeatable agent behavior, install the [Scrinly agent skill](/docs/guides/agent-skill).