MCP

Troubleshooting

Diagnose discovery, cached tools, and authorization failures.

Use the symptom and boundary below before recreating a connector.

## The client cannot discover OAuth

Use `https://data.upscrape.com/mcp` with optional profile/pinning parameters. The OAuth resource itself remains `https://data.upscrape.com/mcp`. Do not point the client at `https://app.upscrape.com`. The client must be able to follow protected-resource and authorization-server metadata.

## The browser signs in but authorization does not finish

Allow redirects between the data resource and app authorization hosts. Browser sessions are host-scoped, and the consent form must submit within the authorization host's content-security policy.

## The tool list looks stale

Some clients cache MCP tool lists per connector. Reconnect or recreate the connector after changing platform or capability pinning. The server currently advertises `listChanged: false`.

## A capability is missing

Search without a platform or category filter, then confirm that the account can see the platform in the public or authenticated catalog. Pinning cannot bypass visibility policy.

## Execution returns a business error

Tool and business failures use `isError: true` inside the JSON-RPC result. Inspect that tool content. JSON-RPC protocol errors are reserved for malformed requests, unknown methods, and invalid tool parameters.

## A result is incomplete

Look for the explicit truncation marker. Previews default to 24 KiB of structured
content. Call `upscrape_get_job_result` with `format: "json_chunk"` and
`byte_offset: 0`, then follow `next_byte_offset` until `has_more` is false. This
uses the existing OAuth or API-key connection; see [jobs and results](/docs/mcp/jobs-and-results).

## A slow execution never finishes in the first call

Use the returned `job_id` with `upscrape_get_job_result`. The default MCP wait is bounded and does not promise that every capability completes within one tool call.


## A retry reports `idempotency_conflict`

Keep the original inputs and job deadline when reusing `operation_key`. A batch
also requires the same ordered items and total ceiling. Retrieve accepted job
handles before deciding to submit intentional new work with a new key.

## A stdio-only client cannot connect

Download the bridge from `/clients/upscrape_mcp_stdio.py` on the app host and run
it with Python 3.10 or newer. Set `UPSCRAPE_API_KEY` through the client's secret
environment (the older name `UPSCRAPE_MCP_TOKEN` still works). The bridge does not perform OAuth login/refresh; use an API key for
unattended clients. It refuses redirects, so configure the canonical data-host URL.
See [Connect MCP](https://app.upscrape.com/app/mcp) for the generated configuration.

## Research returns no results

Research searches completed jobs already saved in your account. Collect data with
a standard profile first. Check your platform/capability grant and `jobs:read`
API-key permission. Changing profiles never grants additional access.

Use the symptom and boundary below before recreating a connector.

The client cannot discover OAuth

Use https://data.upscrape.com/mcp with optional profile/pinning parameters. The OAuth resource itself remains https://data.upscrape.com/mcp. Do not point the client at https://app.upscrape.com. The client must be able to follow protected-resource and authorization-server metadata.

The browser signs in but authorization does not finish

Allow redirects between the data resource and app authorization hosts. Browser sessions are host-scoped, and the consent form must submit within the authorization host's content-security policy.

The tool list looks stale

Some clients cache MCP tool lists per connector. Reconnect or recreate the connector after changing platform or capability pinning. The server currently advertises listChanged: false.

A capability is missing

Search without a platform or category filter, then confirm that the account can see the platform in the public or authenticated catalog. Pinning cannot bypass visibility policy.

Execution returns a business error

Tool and business failures use isError: true inside the JSON-RPC result. Inspect that tool content. JSON-RPC protocol errors are reserved for malformed requests, unknown methods, and invalid tool parameters.

A result is incomplete

Look for the explicit truncation marker. Previews default to 24 KiB of structured content. Call upscrape_get_job_result with format: "json_chunk" and byte_offset: 0, then follow next_byte_offset until has_more is false. This uses the existing OAuth or API-key connection; see jobs and results.

A slow execution never finishes in the first call

Use the returned job_id with upscrape_get_job_result. The default MCP wait is bounded and does not promise that every capability completes within one tool call.

A retry reports `idempotency_conflict`

Keep the original inputs and job deadline when reusing operation_key. A batch also requires the same ordered items and total ceiling. Retrieve accepted job handles before deciding to submit intentional new work with a new key.

A stdio-only client cannot connect

Download the bridge from /clients/upscrape_mcp_stdio.py on the app host and run it with Python 3.10 or newer. Set UPSCRAPE_API_KEY through the client's secret environment (the older name UPSCRAPE_MCP_TOKEN still works). The bridge does not perform OAuth login/refresh; use an API key for unattended clients. It refuses redirects, so configure the canonical data-host URL. See Connect MCP for the generated configuration.

Research returns no results

Research searches completed jobs already saved in your account. Collect data with a standard profile first. Check your platform/capability grant and jobs:read API-key permission. Changing profiles never grants additional access.

Credit prices and plans: Upscrape pricing