Skip to main content
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 Bringits MCP server exposes Unblocker and Stream as native tools via the Model Context Protocol (MCP). AI IDEs (Cursor, VS Code, Claude Code) and LLM agent frameworks can call the tools directly, without writing any HTTP or proxy logic. MCP endpoint: https://unblocker.bringits.com/mcp The same endpoint serves two groups of tools: Your client shows the full, current tool list after you connect.

Setup

There are two ways to connect: With OAuth you add only the URL, and your client opens a browser window for you to sign in the first time; it refreshes the session on its own after that. With client credentials your code exchanges a client ID and secret for a short-lived access token and sends it as Authorization: Bearer <access-token>. With an API token you send Authorization: Bearer <your-api-token> on every call. To get an API token, see Token acquisition.
Do not share your token or commit it to code. Store it in a secret manager or your IDE’s secure credential store.
Every tool runs as your account: requests count toward your plan’s quota, and Stream tools act only on your own projects.

Cursor / VS Code

Open ~/.cursor/mcp.json (create the file if it does not exist) and add:
Reload the window (Cmd+Shift+P → Developer: Reload Window), then go to Cursor Settings → MCP and sign in when prompted. bringits-unblocker then shows as connected, with its tools enabled.
The endpoint path is /mcp, not /sse. Using /sse returns a 404.

Claude Code

Run this command once in your terminal:
Start a new Claude Code session, run /mcp, select bringits-unblocker, and sign in. You should then see its tools, including unblocker_post_request.

Servers and scripts (client credentials)

Use this for anything that runs without a person: a backend service, a scheduled job, or a headless agent. One client ID and secret works for every tool, Stream and Unblocker. Bringits issues the credential to your account; contact support@bringits.com to get one.
1

Exchange the credential for an access token

POST your client ID and secret to the token endpoint:
The response contains access_token and expires_in (seconds). Use only access_token. Ignore refresh_token: do not store it and do not send it anywhere.
2

Call the MCP endpoint with the access token

Send Authorization: Bearer <access-token> on every MCP request to https://unblocker.bringits.com/mcp.
3

Cache the token and exchange again before it expires

Keep the access token in memory and reuse it until shortly before expires_in runs out (for example, 60 seconds early). Then repeat step 1 with the same client ID and secret. Do not exchange on every call.
Build the Authorization: Bearer header from BringitsToken.get() on each MCP call, so a renewed token is picked up automatically.
Keep the client secret in a secret manager. Never commit it to source control or put it in a client-side app.

Headless agents (API token)

API tokens (JWT) are still accepted. We recommend moving machine callers to client credentials; API token support ends at a cutoff date that Bringits announces to affected customers in advance.
If your client cannot open a browser and you have not moved to client credentials yet, send your API token as a header instead. Only unblocker_post_request works this way; Stream tools need the sign-in flow or client credentials.
With Claude Code, add --header "Authorization: Bearer <your-api-token>" to the claude mcp add command above.

Request parameters

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. 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 browser. The browser executes JavaScript, resolves dynamic content, and returns fully rendered HTML. 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

Response format

The tool returns a JSON object that wraps the Unblocker’s POST /request response: Read the target’s outcome from content.status and content.body. A target that blocks you or fails still arrives as statusCode: 200 with, for example, content.status: 403. Example response:

Errors

Invalid country code

If a value in countries is not in the list_countries list, the tool does not send the request and returns only an error message:

Authentication failure

If you are not signed in, or your session can no longer be refreshed, the server answers HTTP 401 and your client asks you to sign in again.

Unblocker errors (reflected in statusCode)

When the Unblocker itself cannot complete the request, statusCode is the Unblocker’s HTTP status and content.error holds one of the nine public error codes. The most common:

Target errors (reflected in content.status)

When the Unblocker reaches the target but the target returns an error, statusCode is 200 and content.status is the target’s status code. Silent 200 challenge pages: Some anti-bot systems return content.status: 200 while serving a challenge or CAPTCHA page. If content.body 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.

Usage examples

GET request (minimal)

POST with JSON body

Geo-restricted target

Browser-rendered page

Best practices

  • Sign in through your MCP client’s OAuth flow in an IDE, and use client credentials for machines. Do not paste tokens into config files or commit them to source control.
  • Always attempt HTTP mode first. Browser mode is 3x slower and significantly more resource-intensive.
  • Check statusCode (the Unblocker) and content.status (the target): a statusCode of 200 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.