MCP (AI Agent Access)

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). 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.

Do not share your token or commit it to code. Store it in a secret manager or your IDE’s secure credential store.

Cursor / VS Code

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

{
  "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:

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:

{
  "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:

{
  "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)

# Via AI agent tool call
method: GET
url: https://example.com/api/data

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

POST with JSON body

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

Geo-restricted target

method: GET
url: https://example.com/us-only-content
countries: ["US"]

Browser-rendered page

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.

Unblocker request reference — full HTTP API documentation for direct integration
Unblocker overview — product overview and token acquisition

​Overview

​Setup

​Cursor / VS Code

​Claude Code

​Request parameters

​Fetch modes

​HTTP mode (default)

​Browser mode

​How to choose

​Response format

​Errors

​HTTP 400 — invalid input

​HTTP 401 — authentication failure

​Target errors (reflected in statusCode)

​Timeout

​Usage examples

​GET request (minimal)

​POST with JSON body

​Geo-restricted target

​Browser-rendered page

​Best practices

​Related

Overview

Setup

Cursor / VS Code

Claude Code

Request parameters

Fetch modes

HTTP mode (default)

Browser mode

How to choose

Response format

Errors

HTTP 400 — invalid input

HTTP 401 — authentication failure

Target errors (reflected in `statusCode`)

Timeout

Usage examples

GET request (minimal)

POST with JSON body

Geo-restricted target

Browser-rendered page

Best practices

Related