Skip to main content

​
Getting connected

No. Your regular 2extract API key works, with the same scopes. Create one in the Dashboard under API Keys.Name it after the client that will use it - Cursor MCP, Claude Code MCP - so you can revoke the right one later without hunting.
For a read-only agent: proxies:read, balance:read, stats:read, geo:read.To let it create and configure proxies, add proxies:write.proxies:write does not include proxies:read. The scopes are independent, and an agent almost always reads before it writes - so a write-only key fails partway through most workflows.
Because /mcp speaks the Model Context Protocol, not HTML. Opening https://mcp.2extract.com without the path gives you a normal page instead.Nothing is wrong - the endpoint is meant for your client, not your browser.
In order of likelihood:
  1. The config file was not reloaded - restart the client. Claude Desktop in particular needs a full restart, not just a new conversation.
  2. The /mcp path is missing from the URL.
  3. The JSON has a syntax error. Most clients fail silently on a malformed config.
Client-specific steps are on each client page.

​
Cost and safety

The server is free. You pay for the proxies your agent creates and the traffic they carry, at the usual pay-as-you-go rates - see Billing & Usage.Read-only tools - balance, usage, geo lookup - never cost anything.
Yes, if you give it a proxies:write key. Creating a proxy is a billable action, and it is not marked destructive in the protocol, so a client will not necessarily stop to confirm.Three ways to bound this:
  • Give read-only keys to agents that only need to look.
  • Say the budget in the request: “cap it at 20 GB a month”. The agent applies the limit at creation.
  • Set setProxyLimits on every proxy. A capped proxy stops passing traffic instead of draining your balance.
See Provisioning & Cost Control.
Only with a proxies:write key, and deleteProxyResource is marked destructive with an explicit confirm parameter - a well-behaved client shows you what is about to happen and waits.That protection depends on your client honouring the marker. If deletion would be unacceptable, do not hand the agent a write-scoped key.deactivateProxyResource is the safe alternative: it stops traffic and can be undone.
A limit is not enforced at the moment it is set. When usage crosses the ceiling, the proxy moves to a suspended status in the background and stops passing traffic. It resumes at the start of the next period, or when you raise the limit.Your other proxies are unaffected.

​
Behaviour

Yes, and usually it should. The country is a parameter in the connection username, not a property of the proxy resource. One proxy plus three usernames covers three countries.The country field on the resource is only the default used when the username carries no geo parameter.
No. Proxy names are immutable, because the name is part of the connection username - renaming would break every string already in use.The description is free text and can be changed at any time.
The country list is long and returns a capped page unfiltered. Searching by name is both faster and more reliable, so the tool descriptions steer the agent that way.If the agent ever reports that a country is unavailable, ask it to search by the exact name before believing it.
Replaces. setProxyIpWhitelist overwrites the whole list.To add one entry, the agent reads the current list and sends it back with the addition. Phrase requests as “add X to the whitelist” rather than “set the whitelist to X” so it reads first.

​
When something fails

The agent surfaces the error code. This is what each means.
Validation errors - a malformed date, a name with a hyphen in it - come back as a human-readable message rather than a code. The agent reads the message and usually corrects itself on the next attempt.

​
Still stuck?

Common Problems

Connection issues that are about the proxy, not the agent.

Contact Support

Include the tool name and the exact error the agent reported.