> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2extract.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Common questions about the 2extract MCP server: keys and scopes, cost, safety, limits, and what to do when a tool fails.

## Getting connected

<AccordionGroup>
  <Accordion title="Do I need a separate key for MCP?">
    No. Your regular 2extract API key works, with the same scopes. Create one in the [Dashboard](https://2extract.com/app/api-keys) 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.
  </Accordion>

  <Accordion title="Which scopes does the agent need?">
    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.
  </Accordion>

  <Accordion title="Why does the endpoint show an error in my browser?">
    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.
  </Accordion>

  <Accordion title="My client shows no 2extract tools at all">
    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](/ai/clients/claude-code).
  </Accordion>
</AccordionGroup>

***

## Cost and safety

<AccordionGroup>
  <Accordion title="Does the MCP server cost anything?">
    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](/guides/billing-usage).

    Read-only tools - balance, usage, geo lookup - never cost anything.
  </Accordion>

  <Accordion title="Can an agent spend my money without asking?">
    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](/ai/use-cases/provisioning-cost-control).
  </Accordion>

  <Accordion title="Can an agent delete my proxies?">
    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.
  </Accordion>

  <Accordion title="What happens if the agent hits my traffic limit?">
    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.
  </Accordion>
</AccordionGroup>

***

## Behaviour

<AccordionGroup>
  <Accordion title="Can one proxy cover several countries?">
    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.
  </Accordion>

  <Accordion title="Can I rename a proxy the agent created?">
    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.
  </Accordion>

  <Accordion title="Why does the agent search for a country instead of listing them all?">
    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.
  </Accordion>

  <Accordion title="Does the whitelist tool add or replace?">
    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.
  </Accordion>
</AccordionGroup>

***

## When something fails

The agent surfaces the error code. This is what each means.

| Code                             | Meaning                               | What to do                                                                     |
| :------------------------------- | :------------------------------------ | :----------------------------------------------------------------------------- |
| `unauthorized`                   | Key missing, wrong, or expired        | Check the `Authorization` header in your client config                         |
| `insufficient_balance_for_proxy` | Not enough funds for the chosen plan  | Top up, or pick a cheaper plan                                                 |
| `plan_required`                  | The tariff ID does not exist          | Ask the agent to re-read `listProxyPlans`                                      |
| `proxy_list_name_duplicate`      | A proxy with that name already exists | Names are unique per account and immutable - pick another                      |
| `not_found`                      | No proxy with that ID                 | The ID is stale or the proxy was deleted                                       |
| `invalid_request`                | The proxy ID is not a valid ID at all | Ask the agent to re-read the proxy list rather than reusing an ID from earlier |
| `cannot_modify_deleted_proxy`    | The proxy is already deleted          | Nothing to do - create a new one                                               |
| `proxy_pool_unavailable`         | No IP could be allocated right now    | Retry shortly with the same arguments                                          |
| `too_many_requests`              | Rate limit                            | Wait and retry with backoff                                                    |

<Note>
  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.
</Note>

***

## Still stuck?

<CardGroup cols={2}>
  <Card title="Common Problems" icon="wrench" href="/help/common-problems/407-proxy-authentication-required">
    Connection issues that are about the proxy, not the agent.
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@2extract.com">
    Include the tool name and the exact error the agent reported.
  </Card>
</CardGroup>