Usage and troubleshooting
Understand automatic routing, product access, account usage, limits, and errors for the hosted Web MCP.
The hosted Web MCP uses your account's existing SERP API, Web Scraping API, and Browser API access. Your MCP token connects an agent to those services; it does not activate a product or add quota.
Which tools are available?
The server checks current product access when your client connects and on subsequent requests. Active access can include a valid trial. Your client discovers only the tools supported by that access.
| Your account has access to | Available tools | Default page-reading service |
|---|---|---|
| SERP API only | web_search | None |
| Web Scraping API only | web_read, web_read_more | Web Scraping API |
| Browser API only | web_read, web_read_more | Browser API |
| Web Scraping API and Browser API | web_read, web_read_more | Web Scraping API |
| SERP API and either reading service | All three tools | Web Scraping API when available, otherwise Browser API |
Without SERP API access, web_search is unavailable. An agent can still read a URL you provide if your account has a reading service. Adding an MCP token does not bypass the SERP API requirement.
An account without any supported product access cannot connect. If a product's quota is exhausted, its tool can still appear in discovery, but the API request returns a quota error. After changing product access or rotating a service API key, reconnect your MCP client to refresh the session and tool list.
Automatic routing
For a normal web_read call, the agent supplies a URL. The server selects Web Scraping API when your account has access to it; otherwise, it selects Browser API. Web Scraping API remains the default when you have both products.
An advanced caller can select an available service with the optional backend argument: "web-scraping-api" or "browser-api". The returned backend field records which service handled the page.
A failed request or exhausted quota does not automatically switch the request to another product. Selecting a different service requires an explicit new tool call and access to that service.
JavaScript rendering
Web Scraping API reads are static by default. If a page contains little useful text and depends on JavaScript, the agent can make another web_read call with render_js: true. This is a new fetch with normal product usage.
Browser API always renders JavaScript. Omit render_js or set it to true for Browser API; false is rejected before the API request. The rendering flag does not select a different service. A thin Browser API result has already been rendered, so repeating it just to enable JavaScript is unnecessary.
How usage is counted
| Action | Account usage |
|---|---|
web_search | Uses your SERP API allowance under its existing billing rules |
web_read through Web Scraping API | Uses your Web Scraping API credits under its existing billing rules |
web_read through Browser API | Uses your Browser API bandwidth allowance, including upload and download traffic |
web_read_more | Reads the stored capture; makes no additional API request or API charge |
Browser API traffic is accounted for when its browser connection closes, so usage may not appear immediately. The search limit only caps the results returned to the agent; it does not change the API's billing rules.
Each new web_read fetches again, including repeated reads of the same URL and explicit retries with JavaScript rendering. These calls receive separate source IDs and use the selected product's normal metering. There are no automatic retries or rendering upgrades in the MCP adapter.
Cancelling a tool call stops its in-flight request where possible. It does not guarantee that usage already incurred is reversed. Disconnecting the client alone is not an explicit cancellation.
Limits and capture lifetime
| Limit | What it means for your agent |
|---|---|
| 10 MiB downloaded HTML per page | Oversized pages return an error |
| 16 KiB serialized tool result | Large readable pages arrive in chunks; use web_read_more for the rest |
| One-hour capture lifetime | Follow next_cursor promptly; captures can become unavailable earlier through cache eviction or a service restart |
| 10 MiB stored captures per token | Earlier captures may be evicted as new pages are read; storage is also subject to shared capacity |
| 55-second upstream timeout; 60-second API client deadline | Set your MCP client's tool timeout above 60 seconds |
| Four concurrent tool calls per token | Limit parallel work; underlying product and service capacity limits also apply |
| Four active sessions per token | Close unused client connections before opening more |
| 15 minutes idle or one hour per session | The client must initialize a new session after expiry |
| 1,000 requests per session | Initialize a new session when the request limit is reached |
Captures are temporary, immutable snapshots. web_read_more continues the same snapshot and never silently fetches the page again. When a capture has expired or been evicted, make a new explicit web_read if you still need the page. That fetch can incur usage and may contain different content; do not combine it with old chunks as though they were one snapshot.
Use the exact source_id and next_cursor from the preceding result, passing next_cursor as the next call's cursor. Stop when next_cursor is null. Source IDs and cursors cannot be shared between MCP tokens.
Connection problems
| Symptom | What to check |
|---|---|
| HTTP 401 or an invalid-token message | Use the dedicated MCP token from Dashboard → MCP in the client's bearer-token field. Check for a revoked token or missing Bearer prefix when configuring the header yourself. A product API key is not an MCP token. |
| HTTP 403 or no active product access | Check that the account has current SERP API, Web Scraping API, or Browser API access. If access changed, reconnect. |
| The client only offers OAuth sign-in | Use a client that supports Streamable HTTP and custom bearer headers. OAuth-only clients are not supported. |
| A browser-based client reports an origin or CORS error | Its origin must be supported by the hosted endpoint. Contact support with the client name and origin; do not send your token. |
| HTTP 404 after a working connection | The session may have expired or been invalidated by a service-key or access change. Reconnect and discover tools again. |
| HTTP 429 | Reduce parallel requests or close unused sessions, then retry later. If the message reports the session request limit, reconnect instead. Product rate limits can also apply. |
| HTTP 503 while authenticating | Authorization is temporarily unavailable. Wait and reconnect. |
| Opening the endpoint in a browser returns HTTP 405 | The endpoint expects an MCP client using Streamable HTTP. It is not a webpage or a standalone event-stream URL. |
Tokens are created and revoked by the account owner on MCP. A token is shown only once when created; if you lose it, revoke it and create another. Revocation blocks further requests, including continuation calls. Never paste a token or product API key into tool arguments, page URLs, source citations, or support messages.
Tool errors
| Error | Next step |
|---|---|
INVALID_INPUT or a tool argument validation error | Check the tool reference. Use a public HTTP(S) URL, a two-letter country code, and arguments supported by your chosen service. |
ENTITLEMENT_DENIED | Check access to the selected product or option. An optional backend override cannot enable a product. |
AUTHENTICATION_FAILED | The selected product rejected its service credential. Check the product's status in your dashboard and reconnect after any service-key change. |
QUOTA_EXCEEDED | Check the selected product's remaining allowance. The server will not automatically use another product's quota. |
RATE_LIMITED | Reduce concurrency and retry later. Respect a supplied retry_after_seconds value when present. |
TIMEOUT | The API request exceeded its deadline. An explicit retry is a new request and can incur usage. |
CANCELLED | The call was cancelled. Retry only if the result is still needed. |
UNSUPPORTED_CONTENT | Use an HTML page with a supported text encoding. This tool does not extract text from downloads such as PDFs or images. |
CONTENT_TOO_LARGE | Select a smaller page or a more focused source. |
UNREADABLE_PAGE | Try another source, or explicitly enable rendering for a Web Scraping API page that needs JavaScript. |
SOURCE_EXPIRED | The capture is unavailable. Read the URL again explicitly if needed. |
INVALID_CURSOR | Pass the unchanged cursor returned for the same source and MCP token. |
UPSTREAM_ERROR or INVALID_RESPONSE | The API request failed or returned unusable data. Retry explicitly if appropriate, or contact support if the issue persists. |
A successful response with content_thin: true is a warning that little readable content was found, not evidence that the page answered the question. The agent should seek another source or, where appropriate, explicitly request rendering before writing a supported answer.
Return to getting started for connection setup, or use the tool reference for arguments and source metadata.