Agents and MCP

The skill, the MCP server, and what the API records about agent traffic.

An AI agent is a normal client. It gets no private endpoint, no separate pricing and no parallel billing path — the same key, the same quota, the same error codes. What follows is only about making the contract easy to consume correctly.

The agent skill

One file, no dependencies, no process to keep alive. It tells an agent how to call /v1/take and /v1/animate, how to read the error envelope, and — the part agents get wrong most often — which error codes are worth retrying and which will fail identically on a fourth attempt.

curl -sS https://api.pagecapture.dev/skill.md -o SKILL.md

Copy it into the skills directory your client reads and put PAGECAPTURE_API_KEY in the agent's environment. The retryable list inside it is generated from the same error catalog that drives the API, so it cannot drift from what the service actually does.

The MCP server

{
  "mcpServers": {
    "pagecapture": {
      "command": "npx",
      "args": ["-y", "@pagecapture/mcp"],
      "env": { "PAGECAPTURE_API_KEY": "your key" }
    }
  }
}

Three tools: capture_screenshot returns the image inline, capture_pdf returns a temporary signed URL, extract_content returns Markdown, text or rendered HTML. The server is stateless — each tool call is one HTTP request, with no browser session held between calls — and your key never leaves your machine. It is not embedded in the published package.

Prefer extract_content over a screenshot whenever the agent needs to read the page. Same credit, and the result is text the model can reason about.

Reading the contract as a machine

/llms.txt — what the API is, in one page.
/llms-full.txt — every parameter, default, limit and error code inline.
/openapi.json — the same contract as OpenAPI 3.1.

All three are generated from the same inventory that validates requests. A parameter that is not in them does not exist, and sending it is a rejected request rather than a silently ignored field.

The integration header

curl -G https://api.pagecapture.dev/v1/take \
  -H "X-Access-Key: $PAGECAPTURE_KEY" \
  -H "X-PageCapture-Integration: agent" \
  --data-urlencode "url=https://example.com"

Optional. It declares how the call reached us — agent, mcp, cli, sdk or direct — and nothing more. We record the channel; we never record which agent, which model, or anything about the person on the other side, because nothing in a request proves any of that and guessing would be worse than not knowing.

Values outside that list are discarded rather than stored. The header is not a capture parameter: it does not appear in the request spec, does not change the output and is not part of the cache key, so the same page captured from the MCP server and from curl still shares one cache entry.

Our own MCP server and CLI set it for you. The SDKs already identify themselves with X-PageCapture-Client, which is enough to be counted as sdk.