solvegate-mcp

This is an MCP server that allows an agent to handle Cloudflare Turnstile: check whether a page has one, and if it does, clear it.

There are three tools. One of them requires no key.

Installation

npx solvegate-mcp

For Claude Desktop / any MCP client, add the following to your configuration:

{
  "mcpServers": {
    "solvegate": {
      "command": "npx",
      "args": ["-y", "solvegate-mcp"],
      "env": { "SOLVEGATE_API_KEY": "sk_test_…" }
    }
  }
}

SOLVEGATE_API_KEY will still work even if inspect_page is not set. This is intentional: you should be able to see what this server does before deciding whether to sign up for anything.

You can get a key at solvegate.io. The free sk_test_ sandbox key requires no card and returns a deterministic token immediately. It is suitable for setting this up, and it never actually clears a real gate.

Related MCP server: cloudscraper-mcp

Why inspect_page exists

The most common mistake when using a solver is to call it before first verifying what is actually on the page. Most cases like this fall into three categories:

• The page is protected by reCAPTCHA or hCaptcha, not Turnstile. These are different products from different vendors. This server does not solve them, and neither does SolveGate. inspect_page will clearly tell you which one it is instead of having you discover it through a 422 error.

• It is a WAF challenge, not a widget. A full-page Cloudflare interstitial has no data-sitekey because the challenge belongs to a zone rule rather than an embedded widget. There is nothing to read from the page, and the gate type is waf, not turnstile.

• The sitekey is rendered from a script after page load. In that case, it is not present in the served HTML at all. The tool will tell you that instead of guessing.

Inspecting a page is free, takes only a second, and is very often the entire solution.

What information it will not provide

Widget mode. The managed, non-interactive, and invisible states are stored on the widget within the Cloudflare account that owns the sitekey. The page only carries the key, so no tool can read the mode from the source alone — including this one or any other that claims to do so.

This does not affect solving: all three modes result in the same request. You provide a sitekey, a page URL, and receive a token back.

The one exception is the five documented dummy sitekeys from Cloudflare, whose widget types are published by Cloudflare. inspect_page reports these, and if you find one on a page, it indicates that you are looking at a staging build rather than production.

Configuration

The key is read from the environment and is never exposed as a tool argument. A tool argument is visible to the model and may appear in transcripts.

Behavior Notes

Solving is performed asynchronously internally. solve_turnstile creates the solve with async: true and polls the result, rather than holding a connection open across the entire attempt. An agent’s tool call has a timeout that it cannot control, and a synchronous solve can make a slow gate look like a dead tool. Additionally, if a timeout occurs, a solve reference remains available: the error will mention it, and get_solve can retrieve the solve rather than losing one that has already been billed.

Errors are returned as results, not exceptions. Every failure is returned as an isError result that includes SolveGate’s own error.code — such as balance_empty, unknown_sitekey, rate_limited, or forbidden_target. A model can act on these values, and there is no reliable action to take from a stack trace.

Tokens are single-use and short-lived. expiresAt is specified in Unix seconds. Once past this time, Cloudflare no longer accepts the token, and the solve record is just a history entry. Request a token at the moment you submit it.

Check mode before trusting a token. An sk_test_ key causes mode: "sandbox" to be returned, and a sandbox token will not clear a real gate. This field ensures that a test key used in a production configuration fails clearly and loudly, rather than silently.

Acceptable Use

Only solve against properties you own or are authorized to test. This server is meant for end-to-end tests that keep failing on a challenge, CI environments for your own staging, and synthetic monitoring of your own production. The acceptable use policy is the binding version. Targets on a denylist always return 403 forbidden_target, no matter what an agent requests.

Development

npm install
npm run build
npm test          # spawns the built server and speaks MCP to it
OFFLINE=1 npm test  # skips the two tests that reach the network

The tests run through a real stdio transport rather than the callback functions directly. This is intentional: a schema that the SDK rejects at registration, or a stray write to stdout — which corrupts the transport because stdout is the transport — only appears when something actually goes through the protocol.

Links

• SolveGate API reference

• OpenAPI specification

• Turnstile Checker — same inspection provided by this server, also available in a browser.

• Turnstile error index

MIT.