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

# MCP (AI Agent Access)

> Use Unblocker natively in Cursor, Claude Code, and any MCP-compatible AI agent

> Connect your AI IDE or agent framework to the Unblocker with a single server URL. No proxy configuration. No HTTP client code. Your agent calls the tool; the Unblocker handles the rest.

## Overview

The Unblocker MCP server exposes Unblocker as a native tool via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). AI IDEs (Cursor, VS Code, Claude Code) and LLM agent frameworks can call the tool directly, without writing any HTTP or proxy logic.

**MCP endpoint:** `https://unblocker.bringits.com/mcp`

The server exposes one tool: **`unblocker_post_request`**.

## Setup

You need an **Unblocker API token** to connect. Contact your BringIts account manager to obtain one.

<Note>
  Do not share your token or commit it to code. Store it in a secret manager or your IDE's secure credential store.
</Note>

### Cursor / VS Code

Open `~/.cursor/mcp.json` (create the file if it does not exist) and add:

```json theme={null}
{
  "mcpServers": {
    "bringits-unblocker": {
      "type": "http",
      "url": "https://unblocker.bringits.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}
```

Reload the window (`Cmd+Shift+P` → `Developer: Reload Window`), then go to **Cursor Settings → MCP**. You should see `bringits-unblocker` listed with **1 tool enabled**.

> The endpoint path is `/mcp`, not `/sse`. Using `/sse` returns a 404.

### Claude Code

Run this command once in your terminal:

```bash theme={null}
claude mcp add --transport http bringits-unblocker \
  https://unblocker.bringits.com/mcp \
  --header "Authorization: Bearer <your-api-token>" \
  --scope user
```

Start a new Claude Code session after running the command. Verify with `/mcp` — you should see `bringits-unblocker` with 1 tool: `unblocker_post_request`.

## Request parameters

| Parameter   | Type      | Required | Description                                                                                                   |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `method`    | string    | Yes      | HTTP method for the target: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`                                   |
| `url`       | string    | Yes      | Full target URL, including scheme (e.g. `https://example.com/page`)                                           |
| `headers`   | object    | No       | Headers to send to the target. Not forwarded in browser mode                                                  |
| `body`      | string    | No       | Request body for `POST` and `PUT`. Stringify JSON payloads before passing                                     |
| `countries` | string\[] | No       | ISO 3166-1 alpha-2 country codes (e.g. `["US", "DE"]`). Restricts proxy selection to IPs from those countries |
| `browser`   | boolean   | No       | When `true`, loads the page in a headless browser and returns rendered HTML. Defaults to `false`              |

## Fetch modes

`unblocker_post_request` supports two modes, controlled by the `browser` parameter. Always start with HTTP mode. Escalate to browser mode only after HTTP mode has failed.

### HTTP mode (default)

`browser: false` — Sends a standard HTTP request through the Unblocker proxy. The proxy handles IP rotation and request fingerprinting.

| Property             | Value      |
| -------------------- | ---------- |
| Timeout              | 30 seconds |
| Speed                | Fast       |
| JavaScript execution | No         |

Best for: REST APIs, JSON endpoints, and any page that does not require JavaScript to render its content.

### Browser mode

`browser: true` — Loads the page in a headless Chromium browser. The browser executes JavaScript, resolves dynamic content, and returns fully rendered HTML.

| Property             | Value                  |
| -------------------- | ---------------------- |
| Timeout              | 90 seconds             |
| Speed                | Slow                   |
| JavaScript execution | Yes (full page render) |

Best for: pages protected by Cloudflare, Incapsula, or PerimeterX that return a challenge page to plain HTTP requests, and Single Page Applications (SPAs) that require JavaScript to render content.

> Browser mode is significantly more resource-intensive than HTTP mode. Use it only after HTTP mode has failed — including a retry with full browser-like headers (`User-Agent`, `Accept`, `Accept-Language`, `Referer`).

### How to choose

```
1. Try HTTP mode first
   → unblocker_post_request (browser: false)

2. Response is a challenge page or 403?
   → Retry with browser-like headers (browser: false)

3. Still blocked?
   → Escalate to browser mode (browser: true)
```

## Response format

All responses return `Content-Type: application/json`.

| Field        | Type             | Description                                                                                                                   |
| ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `url`        | string           | The original target URL                                                                                                       |
| `content`    | string or object | Target response body. Parsed as JSON when the target returns `Content-Type: application/json`, otherwise returned as a string |
| `statusCode` | integer          | HTTP status code returned by the target                                                                                       |
| `requestId`  | string           | UUID for tracing. Include this in support requests                                                                            |

The outer MCP tool response is always successful if the request reached the target. A `statusCode` of `403` or `500` means the target returned that status — not a failure of the Unblocker itself.

**Example response:**

```json theme={null}
{
  "url": "https://example.com/api/data",
  "content": { "key": "value" },
  "statusCode": 200,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Errors

### HTTP 400 — invalid input

Returned before the request reaches the target, when input validation fails.

| error                  | Meaning                                                                  |
| ---------------------- | ------------------------------------------------------------------------ |
| `INVALID_COUNTRY_CODE` | One or more values in `countries` are not valid ISO 3166-1 alpha-2 codes |
| `MISSING_METHOD`       | The `method` parameter was not provided                                  |
| `MISSING_URL`          | The `url` parameter was not provided or is not a valid URL               |

**Example:**

```json theme={null}
{
  "error": "Invalid country code(s): ['XX']. Must be ISO 3166-1 alpha-2 values."
}
```

### HTTP 401 — authentication failure

Your token is missing, expired, or invalid. Verify the `Authorization: Bearer <token>` header is present and correct.

### Target errors (reflected in `statusCode`)

When the Unblocker reaches the target but the target returns an error, the response is still delivered with `statusCode` set to the target's status code.

| `statusCode`          | Meaning                       | Recommended action                                                            |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------------- |
| `403`                 | Request blocked by the target | Retry with browser-like headers. Escalate to `browser: true` if still blocked |
| `404`                 | Page not found at the target  | Verify the URL is correct                                                     |
| `429`                 | Rate limited by the target    | Add a delay before retrying. Consider using a different `countries` pool      |
| `500` / `502` / `503` | Target server error           | Retry after a short delay                                                     |

**Silent 200 challenge pages:** Some anti-bot systems return `statusCode: 200` while serving a challenge or CAPTCHA page. If `content` contains phrases like "Checking your browser", "Just a moment", or "cf-browser-verification", treat it as a block and follow the escalation steps above.

### Timeout

Requests that exceed the mode timeout result in a tool-level error with no response object. Timeouts are most common in browser mode on heavily protected or slow-loading pages.

| Mode                      | Timeout    |
| ------------------------- | ---------- |
| HTTP (`browser: false`)   | 30 seconds |
| Browser (`browser: true`) | 90 seconds |

## Usage examples

### GET request (minimal)

```bash theme={null}
# Via AI agent tool call
method: GET
url: https://example.com/api/data
```

```json theme={null}
{
  "url": "https://example.com/api/data",
  "content": { "results": [] },
  "statusCode": 200,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### POST with JSON body

```bash theme={null}
method: POST
url: https://api.example.com/search
headers: { "Content-Type": "application/json", "Accept": "application/json" }
body: "{\"query\": \"sports events today\"}"
```

### Geo-restricted target

```bash theme={null}
method: GET
url: https://example.com/us-only-content
countries: ["US"]
```

### Browser-rendered page

```bash theme={null}
method: GET
url: https://protected-site.com/page
headers: {
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "Accept": "text/html,application/xhtml+xml",
  "Accept-Language": "en-US,en;q=0.9"
}
browser: true
```

## Best practices

* Store your token in a secret manager. Do not hardcode it or commit it to source control.
* Always attempt HTTP mode first. Browser mode is 3x slower and significantly more resource-intensive.
* Check both the tool result and `statusCode` — a successful tool call does not mean the target returned a valid response.
* Log `requestId` from every response. Include it when contacting support.
* When using `countries`, have a fallback without geo-restriction in case the requested pool is temporarily unavailable.
* Use browser-like headers (`User-Agent`, `Accept-Language`, `Referer`) in HTTP mode before escalating to `browser: true`.

## Related

* [Unblocker request reference](/unblocker/request) — full HTTP API documentation for direct integration
* [Unblocker overview](/unblocker) — product overview and token acquisition