@sitelensapi/mcp · public docs

Geographic capture

See the web from anywhere. Geographic network exit is a SiteLens Pro feature (capture.geographic). Local MCP tools stay free and do not route through a geographic proxy. Product page: /geographic-capture.

Tools

sitelens_list_capture_countries — GET /capture/geo. Lists configured countries. Does not capture and does not need an API key.
sitelens_capture — POST /capture when SITELENS_API_KEY is set and SITELENS_MODE is all or cloud. Optional location selects the exit country and browser localization.
sitelens_run_flow — saved cloud QA flow. Optional location is forwarded to POST /qa/flows/:flowId/run. Country exit is verified before the run. Saved flow runs also require the Pro qa.flow.run entitlement.

Country selection

Call sitelens_list_capture_countries first. Use a code from datacenterCountryOptions unless you explicitly set proxyType to residential and residentialAvailable is true. The default datacenter list is 18 supported countries, sorted by name. When residentialCountries is null, the server did not publish a finite residential list — do not invent one.

{
  "paidOnly": true,
  "feature": "capture.geographic",
  "defaultProxyType": "datacenter",
  "residentialAvailable": false,
  "datacenterCountries": ["AU", "BR", "CA", "CN", "FR", "DE", "HK", "IN", "IL", "IT", "JP", "NL", "RO", "SG", "KR", "TR", "GB", "US"],
  "datacenterCountryOptions": [
    { "code": "AU", "name": "Australia" },
    { "code": "BR", "name": "Brazil" },
    { "code": "DE", "name": "Germany" }
  ],
  "residentialCountries": null,
  "residentialCountryOptions": null
}

The code list above is the full default, sorted by English name. The options sample shows the name shape; the live response includes one entry per code. A deployment may replace the list with SITELENS_GEO_DC_COUNTRIES. Trust the live catalog. United Kingdom is GB.

Proxy type

datacenter is the default when location.country is set and proxyType is omitted.
residential is used only when you set location.proxyType to "residential".
SiteLens does not fall back from one proxy type to the other, and it does not capture through a direct connection when routing fails.

`sitelens_capture` example

Cloud tools need SITELENS_API_KEY. The placeholder below is not a real key.

{
  "url": "https://example.com/",
  "mode": "browser",
  "location": {
    "country": "DE",
    "proxyType": "datacenter",
    "locale": "de-DE",
    "timezone": "Europe/Berlin"
  }
}

mode is http, html, or browser (default browser). Screenshots require browser. locale and timezone do not require Pro and do not change the network exit. On a local-only MCP server, location.country returns guidance instead of capturing.

Verification results

A successful country capture adds geographic to the tool summary. Proxy usernames and passwords are not included.

{
  "tool": "sitelens_capture",
  "outcome": "captured",
  "mode": "browser",
  "geographic": {
    "provider": "decodo",
    "proxyType": "datacenter",
    "requestedCountry": "DE",
    "observedCountry": "DE",
    "observedIp": "203.0.113.10",
    "verificationStatus": "verified",
    "bytesProxied": 42,
    "bytesProxiedComplete": false
  }
}

verified — observed country matches the request. Evidence is returned.
mismatch — observed country differs. Outcome is failed, failureCode is geo_verification, and evidence is omitted.
unverified — the exit could not be confirmed. Same fail-closed result.
country_unavailable — that country is not in the catalog for the proxy type you asked for.
proxy — routing could not be established. No direct-exit fallback.

bytesProxied counts instrumented response bodies. It is not a provider invoice. For browser mode, bytesProxiedComplete is false because Playwright asset traffic is not fully measured.

Paid-plan restrictions

Free workspaces that send location.country receive HTTP 402 feature_not_entitled for capture.geographic, and no capture starts. The detail is: “Geographic capture (location.country) requires the PRO plan.” Locale-only and timezone-only requests are not subject to that check. Non-geographic capture is not a separate monthly quota.

Saved flows

{
  "flowId": "11111111-1111-4111-8111-111111111111",
  "url": "https://example.com/",
  "location": { "country": "BR", "proxyType": "datacenter" }
}

If the exit cannot be verified, the flow run is rejected before browser steps (HTTP 422) and may include geographic. A completed run stores the same public metadata on result_json.geographic, which sitelens_run_flow copies into summary.geographic.

Multi-country comparison

The dashboard Geographic Capture page can capture one URL from two or more countries (up to the full supported catalog). Each country is a separate POST /capture with its own location.country, exit verification, and result. Failures stay fail-closed and do not cancel other countries. MCP tools still capture one country per call; use the dashboard for multi-country compare, or call sitelens_capture once per country.

Manual verification

Paid captures are not started automatically. On Pro, use the dashboard Geographic Capture page (or sitelens_capture) against browserleaks.com/ip or ipinfo.io/my for BR, DE, JP, and US. Confirm requestedCountry and observedCountry match and verificationStatus is verified. Product checklist: /geographic-capture#manual-verification.