Clients

MCP server

@pageteer/mcp is a Model Context Protocol server (stdio) that gives AI assistants and coding agents Pageteer's web search and page fetching as tools. It is built on the JavaScript client.

Tools

MCP tools
Name	Type	Description
`web_search`	2 credits (0 cached)	q, n, country, language, page, location, engines, max_age; include_content, content_results, content_max_chars, content_mode, unblock (each fetched page costs a render) and include_answer (a cited answer, LLM extraction pricing). Returns numbered results (title, URL, snippet), with the fetched pages and the answer when asked.
`fetch_page`	as render	url, format (markdown by default, or text / html), markdown_mode, mode, unblock, wait_for, max_age, max_chars (20,000 by default), start_index, actions (read-only page actions: scroll, click "Load more", wait). Returns the page content and says where it was cut; call again with start_index to read on.
`extract`	as extract	url plus exactly one of template (lead, product, article, job; LLM only for missing required fields), selectors, structured: true or schema; llm_fallback, mode, unblock, wait_for, max_age, actions. Returns the data as JSON.
`screenshot`	5 credits	url, full_page, max_height, selector (one element), device (e.g. iphone-15, pixel-8, desktop-1080p) or width/height, format (png, jpeg, webp), quality, hide_selectors (cookie banners), dark_mode, omit_background, unblock, max_age, actions. Returns the image.
`map_site`	1 credit (0 when nothing is found)	url, search, limit (1,000 by default), same_path, include_subdomains, use_sitemap. Lists the site's URLs from its sitemaps and the start page's links without fetching them; use it to pick pages before fetch_page or crawl_site.
`crawl_site`	per page	url (or job_id), max_pages (10 by default), max_depth, include/exclude, sitemap, markdown_mode, mode, unblock, wait (true by default), wait_timeout_s (300), output, max_chars. Returns each page’s title, URL and Markdown; output: "markdown" returns the whole site as one Markdown file and "llms.txt" an index of title, URL and summary per page (the export is free). With wait: false it returns a job_id; call again with job_id to check on it.
`watch_page`	per check	Create a monitor: url, name, interval (hourly, 6h, daily, weekly), selector or selectors, markdown_mode, ignore, mode, unblock, webhook_url. Each check costs what fetching the page costs.
`list_monitors / monitor_changes`	free	The monitors with status and last change; a monitor’s change history with diffs and field changes.
`check_monitor / manage_monitor`	per check / free	Check a monitor now and show the diff; pause, resume or delete a monitor.
`check_usage`	free	The plan, credits used and remaining, and when they reset.

API errors come back as tool errors (isError: true) with the code, message, request id and Retry-After, so the model can react to captcha_required or insufficient_credits. A 429 is retried first; a 402 never is, and says why (its reason) and links your Billing page.

Install

Like the JavaScript client, the server is not on npm yet. Build both from the Pageteer repository:

shell

cd /path/to/pageful/clients/js  && npm install   # builds @pageteer/client
cd /path/to/pageful/clients/mcp && npm install   # builds dist/index.js (bin: pageteer-mcp)

Claude Code

shell

claude mcp add pageful --scope user \
  -e PAGETEER_API_KEY=pk_live_… \
  -- node /path/to/pageful/clients/mcp/dist/index.js

Claude Desktop, Cursor and .mcp.json

JSON

{
  "mcpServers": {
    "pageful": {
      "command": "node",
      "args": ["/path/to/pageful/clients/mcp/dist/index.js"],
      "env": {
        "PAGETEER_API_KEY": "pk_live_…",
        "PAGETEER_BASE_URL": "https://api.104-236-84-15.sslip.io"
      }
    }
  }
}

PAGETEER_BASE_URL is optional (default https://api.pageteer.com); point it at another deployment, such as a local gateway, when needed. The server starts and lists its tools even without PAGETEER_API_KEY; tool calls then fail with missing_api_key.

Wiring the server into an agent for the first time? Use a test key (pk_test_…) as PAGETEER_API_KEY: every tool returns deterministic fake results for free, and URLs under https://test.pageteer.com/ such as /error/captcha let you check how the agent handles failures. Swap in a pk_live_… key for real results.

Embedding

TypeScript

import { createServer } from '@pageteer/mcp';
import { Pageteer } from '@pageteer/client';

const server = createServer({ client: new Pageteer({ apiKey }) }); // an McpServer: connect any transport

Each tool call is an ordinary API request: it is charged like the endpoint behind it, shows up in your usage, and follows the acceptable use rules. Use a separate key for agents so you can revoke it on its own.