# Local agents

Let a script or an AI agent on your own machine ask the extension for a capture.

The extension captures the page you are looking at when you click its icon. Two other things can
ask it to capture a page instead: the `page-scanner` command, and an AI agent speaking MCP. Both
are off until you pair them, and both go through the same connection.

## What they share

- **The capture happens in a Chrome you are already signed in to.** A page behind a login is a
  page you are logged into, and no second browser is started.
- **The connection is loopback only.** `127.0.0.1`, never `0.0.0.0`, and nothing leaves the
  machine.
- **One pairing per machine.** A port and a token, written to `~/.page-scanner/config.json` and
  pasted into the extension's settings page once.
- **A background process holds the port.** Nothing outside Chrome can open a connection into an
  extension, so the extension dials out, and something has to be listening before it can. The
  command and the MCP server both talk to that one process, so you can use them at the same time.

## Which one you want

**[The command line](https://docs.pagescanner.app/cli)** if you want to capture a page from a script, a Makefile or a
terminal. `npx @page-scanner/cli scan --url <address> --out <file>` prints the path it wrote and
nothing else.

**[The MCP server](https://docs.pagescanner.app/mcp)** if you want an agent to do it: Claude Code, Claude Desktop, or anything
else that speaks MCP. It is four tools over the same connection.

Installing both is fine. They share the pairing and the background process.

## Pair it

1. Run `npx @page-scanner/cli pair`, or ask your agent to run the MCP server's `pair` tool. It
   prints a port and a token.
2. Open the extension's [settings](https://docs.pagescanner.app/extension/settings). Under **Local agents**, give this browser a
   name, paste the port and the token, and press **Connect**.

Chrome runs a separate copy of the extension in every profile, so repeat step 2 in each profile you
want reachable; your work profile and your personal profile are two browsers here. The
[MCP pairing guide](https://docs.pagescanner.app/mcp/pairing) covers checking and rotating a pairing.

## How an agent's scan differs from a click

- **It always captures the whole page.** An agent has no preview to crop against.
- **There is no raster fallback.** A click can fall back to scrolling and stitching when the
  debugger cannot attach; an agent's scan cannot, so it fails and says so instead of handing back
  an image.

## Off by default, and visible when on

Pairing is a deliberate act: the extension ships with this off, and turning it on means pasting a
token into a settings page. While a scan runs, Chrome shows its own "started debugging this
browser" bar, which no extension can hide, so a scan an agent started is never invisible.