Tools

The default MCP surface uses four tools to keep discovery compact and contracts exact.

upscrape_search_capabilities

Ranks visible capabilities by task keywords, common synonyms, platform names, URL tokens and category. Exact dotted capability IDs stay exact lookups. limit defaults to 5 for a query or 20 for browsing, and is capped at 100. Up to three top matches include input_schema, example_input and schema_hash within the response budget; set include_schema: false for summaries.

{
  "query": "product search",
  "platform": "amazon",
  "limit": 10
}

Results include capability ID, platform, name, description, category, timeout, credit cost, total matches, and whether the list was truncated.

upscrape_describe_capability

Returns the exact input JSON Schema, example input, timeout, credit cost, and whether a safe example output exists.

{"capability": "amazon.products.search"}

Describe when the schema or required details are absent from discovery. Use the supplied schema directly when available; never guess fields from a tool name.

upscrape_execute

Runs one capability:

{
  "capability": "amazon.products.search",
  "input": {},
  "wait": true
}

wait defaults to true. Set it to false, or set wait_ms: 0, to receive a job ID immediately. wait_ms controls this HTTP call only (0–55000 ms); it does not shorten the job deadline. max_credits is an optional integer ceiling checked before a new job is accepted. operation_key (1–128 characters) identifies one logical scrape; reuse it after a timeout or OAuth refresh and use a new key for an intentional new scrape. Reusing a key with different inputs returns idempotency_conflict. An optional positive timeout_ms may shorten the job deadline but cannot exceed the capability's registered timeout.

upscrape_get_job_result

Retrieves a previously started account-scoped job:

{"job_id": "JOB_ID"}

This tool is read-only and does not charge credits.

Top-level arrays support offset and limit pagination. To read complete raw output of any shape, use format: "json_chunk", starting at byte_offset: 0. Follow result_chunk.next_byte_offset and concatenate result_chunk.text until has_more is false. chunk_bytes defaults to 8192 and accepts 4–16384 bytes; the response budget may reduce the returned chunk. See jobs and results for integrity checks.

API keys need jobs:read and permission for the job's platform and capability. OAuth grants may restrict reading by platform or capability. Within the grant, results include jobs created by other applications.

Pinned capability tools

Pinned connections expose selected capabilities as first-class tools in addition to the four meta-tools. Dotted capability IDs become strict-client-safe names by replacing each dot with a double underscore. For example, amazon.products.search becomes amazon__products__search.

Pinned tools accept optional execution controls under _upscrape, such as {"_upscrape":{"wait_ms":0,"max_credits":1,"operation_key":"unique-operation-id"}}. If a capability already defines an _upscrape input property, that property retains its published meaning; use generic execute to supply execution controls separately.

Batch execution

Opt in with ?batch=true (or &batch=true alongside a profile). The extra upscrape_execute_batch tool accepts operation_key, a required total max_credits, and 1–20 items containing capability and input. Every input and the total price are checked before submission. Submissions are sequential; normal account concurrency limits govern actual request execution. Each item returns its job handle or error, and partial reports failures. Accepted items bind the operation to the original ordered inputs and budget; retry the same request to recover handles without creating duplicate jobs. A changed request requires a new operation key. Never include already accepted work in a new batch unless an intentional fresh scrape is wanted.

Research compatibility

?profile=research exposes only search(query) and fetch(id), for research clients that require that interface. Search matches the platform, capability and input of up to 20 completed jobs in this account, ordered newest first. It does not search the live web or launch paid scraping. Fetch uses the exact ID returned by search. Large results expose continuation_id; fetch that ID for the next raw JSON fragment. Concatenate fragments and check sha256 when reconstructing JSON. The returned URL opens the run on the console's Runs page; collected_at is job completion time, not the upstream document's modification date.