Inspect pages for Cloudflare Turnstile and clear Turnstile or WAF challenges to obtain authentication tokens.
Also known as SolveGate/solvegate-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Aug 25, 2026
- License
- MIT
What is SolveGate MCP?
SolveGate inspects pages for Cloudflare Turnstile and clear Turnstile or WAF challenges to obtain authentication tokens.
Summary generated from the project's README
About SolveGate MCP server
Automating the bypass of Cloudflare Turnstile and WAF challenges is what this server enables for developers building web agents. It provides specialized tools to identify if a webpage contains a Turnstile widget or a full-page WAF interstitial, allowing an agent to decide whether to attempt a solve. This prevents wasted resources on pages using different protections like reCAPTCHA or hCaptcha.
Users can run this server locally via npx and connect it to Claude Desktop or any MCP client. The inspect_page tool works without any credentials, making it easy to test functionality immediately. To actually clear challenges and obtain authentication tokens, you must provide a SOLVEGATE_API_KEY in your environment variables. The server includes solve_turnstile for handling the challenge process and get_solve to retrieve results using a specific ID, which is useful if a connection times out during an asynchronous solve.
What you can do with it
- 1Identify Cloudflare protectionsDetermine if a specific URL is protected by a Turnstile widget or a WAF challenge before attempting to solve it.
- 2Obtain authentication tokensClear a Turnstile challenge to receive a valid token for further web automation tasks.
- 3Recover interrupted solve attemptsRetrieve a solve result using an ID if the initial tool call times out.
- 4Verify staging environmentsDetect if a site is running on a staging build by checking for Cloudflare dummy sitekeys.
Written from the project's README. Every use case is checked against a quote from it.
How to install SolveGate MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SolveGate MCP in Claude Code
$ claude mcp add --env 'SOLVEGATE_API_KEY=<YOUR_SOLVEGATE_API_KEY>' solvegate-mcp -- npx -y solvegate-mcpInstall SolveGate MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"solvegate-mcp": {
"command": "npx",
"args": [
"-y",
"solvegate-mcp"
],
"env": {
"SOLVEGATE_API_KEY": "<YOUR_SOLVEGATE_API_KEY>"
}
}
}
}Install SolveGate MCP in VS Code
.vscode/mcp.json
{
"servers": {
"solvegate-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"solvegate-mcp"
],
"env": {
"SOLVEGATE_API_KEY": "<YOUR_SOLVEGATE_API_KEY>"
}
}
}
}Install SolveGate MCP in VS Code CLI
$ code --add-mcp '{"name":"solvegate-mcp","type":"stdio","command":"npx","args":["-y","solvegate-mcp"],"env":{"SOLVEGATE_API_KEY":"<YOUR_SOLVEGATE_API_KEY>"}}'Install SolveGate MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"solvegate-mcp": {
"command": "npx",
"args": [
"-y",
"solvegate-mcp"
],
"env": {
"SOLVEGATE_API_KEY": "<YOUR_SOLVEGATE_API_KEY>"
}
}
}
}Install SolveGate MCP in Codex
$ codex mcp add solvegate-mcp --env 'SOLVEGATE_API_KEY=<YOUR_SOLVEGATE_API_KEY>' -- npx -y solvegate-mcpInstall SolveGate MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.solvegate-mcp] command = "npx" args = ["-y", "solvegate-mcp"] [mcp_servers.solvegate-mcp.env] SOLVEGATE_API_KEY = "<YOUR_SOLVEGATE_API_KEY>"
Install SolveGate MCP in Gemini CLI
$ gemini mcp add -s user -e 'SOLVEGATE_API_KEY=<YOUR_SOLVEGATE_API_KEY>' solvegate-mcp npx -- -y solvegate-mcpInstall SolveGate MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"solvegate-mcp": {
"command": "npx",
"args": [
"-y",
"solvegate-mcp"
],
"env": {
"SOLVEGATE_API_KEY": "<YOUR_SOLVEGATE_API_KEY>"
}
}
}
}Configuration
SOLVEGATE_API_KEYSecretAPI key for solving. Optional — the inspect_page tool works without one, so the server is useful before you have an account. A free sk_test_ sandbox key needs no card.
SOLVEGATE_BASE_URLAPI base URL. Defaults to https://api.solvegate.io.
SOLVEGATE_MAX_WAIT_MSHow long solve_turnstile waits for a pending solve, in milliseconds. Defaults to 60000.
SOLVEGATE_SITE_URLWhere inspect_page runs. Defaults to https://solvegate.io.
SOLVEGATE_TIMEOUT_MSPer-request timeout in milliseconds. Defaults to 30000.
| Name | Description | |
|---|---|---|
| SOLVEGATE_API_KEY | API key for solving. Optional — the inspect_page tool works without one, so the server is useful before you have an account. A free sk_test_ sandbox key needs no card. | Secret |
| SOLVEGATE_BASE_URL | API base URL. Defaults to https://api.solvegate.io. | |
| SOLVEGATE_MAX_WAIT_MS | How long solve_turnstile waits for a pending solve, in milliseconds. Defaults to 60000. | |
| SOLVEGATE_SITE_URL | Where inspect_page runs. Defaults to https://solvegate.io. | |
| SOLVEGATE_TIMEOUT_MS | Per-request timeout in milliseconds. Defaults to 30000. |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesolvegate/solvegate-mcp is public and reachablegithub.com/solvegate/solvegate-mcp ↗Pass
- Package names this repository as its sourcesolvegate-mcp names solvegate/solvegate-mcp as sourcenpmjs.com/package/solvegate-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-25github.com/solvegate/solvegate-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from solvegate-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsolvegate-mcp
An MCP server that lets an agent deal with Cloudflare Turnstile: check whether a page has one, and clear it when it does.
Three tools. One of them needs no account.
| Tool | What it does | Needs a key |
|---|---|---|
inspect_page |
Fetch a URL and report whether Cloudflare Turnstile is on it, its sitekey, how it renders, its data-* configuration, and whether the page is a full-page WAF challenge instead of a widget |
No |
solve_turnstile |
Clear a Turnstile or Turnstile WAF challenge and return a token | Yes |
get_solve |
Fetch a solve by id — free, never re-bills | Yes |
Install
npx solvegate-mcp
Claude Desktop / any MCP client, in your config:
{
"mcpServers": {
"solvegate": {
"command": "npx",
"args": ["-y", "solvegate-mcp"],
"env": { "SOLVEGATE_API_KEY": "sk_test_…" }
}
}
}
Leave SOLVEGATE_API_KEY out and inspect_page still works. That is deliberate:
you should be able to see what the server does before deciding whether to sign
up for anything.
Get a key at solvegate.io. A free sk_test_ sandbox key
needs no card and returns a deterministic token instantly — right for wiring this
up, and it never clears a real gate.
Why inspect_page exists
The commonest wrong turn with a solver is calling it when you should have looked first. Three cases account for most of it:
- The page carries reCAPTCHA or hCaptcha, not Turnstile. Those are different
products from different vendors. This server does not solve them, and neither
does SolveGate —
inspect_pagesays so by name instead of letting you find out from a422. - 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 to a widget you embed. There is nothing to read off the page, and the gate iswafrather thanturnstile. - The sitekey is rendered from script after load. Then it is not in the served HTML at all, and the tool says that rather than guessing.
Inspecting is free, takes about a second, and is quite often the whole answer.
What it will not tell you
The widget mode. Managed, non-interactive and invisible are stored on the widget inside the Cloudflare account that owns the sitekey. The page carries only the key, so no tool can read the mode off the source — including this one, and including anything that claims otherwise.
It does not matter for solving: all three modes resolve to the same request. A sitekey, a page URL, and a token back.
The one exception is Cloudflare's five documented dummy sitekeys, whose widget
type Cloudflare publishes itself. inspect_page reports those, and finding one
on a page tells you something useful — you are looking at a staging build rather
than production.
Configuration
| Variable | Default | What it does |
|---|---|---|
SOLVEGATE_API_KEY |
— | Your key. sk_test_ for the sandbox, sk_live_ for real gates. |
SOLVEGATE_BASE_URL |
https://api.solvegate.io |
API base. |
SOLVEGATE_SITE_URL |
https://solvegate.io |
Where inspect_page runs. |
SOLVEGATE_TIMEOUT_MS |
30000 |
Per-request timeout. |
SOLVEGATE_MAX_WAIT_MS |
60000 |
How long solve_turnstile waits for a pending solve. |
The key is read from the environment and is never a tool argument — a tool argument is model-visible and ends up in transcripts.
Notes on behaviour
Solving is async underneath. solve_turnstile creates the solve with
async: true and polls it, rather than holding a connection open for the whole
attempt. An agent's tool call has a timeout it does not control, and a
synchronous solve makes a slow gate look like a dead tool. It also means a
timeout here leaves you a solve id: the error names it, and get_solve will pick
it up rather than losing a solve that was already billed.
Errors are results, not exceptions. Every failure comes back as an isError
result carrying SolveGate's own error.code — balance_empty, unknown_sitekey,
rate_limited, forbidden_target. A model can act on those. It can do nothing
useful with a stack trace.
Tokens are single-use and short-lived. expiresAt is Unix seconds; past it,
Cloudflare stops accepting the token and the solve record is just a record.
Request a token at the moment you submit it.
Check mode before trusting a token. An sk_test_ key returns
mode: "sandbox", and a sandbox token will not clear a real gate. The field
exists so a test key in a production config fails loudly rather than quietly.
Acceptable use
Solve only against properties you own or are authorised to test. This exists for
end-to-end tests that keep failing on a challenge, CI against your own staging,
and synthetic monitoring of your own production. The
acceptable use policy is the binding version, and
targets on the denylist return 403 forbidden_target regardless of what any
agent asks for.
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 drive a real stdio transport rather than calling the tool callbacks directly. That is on purpose: a schema the SDK rejects at registration, or a stray write to stdout — which corrupts the transport, since stdout is the transport — only shows up when something actually speaks the protocol to it.
Links
- SolveGate API reference
- OpenAPI spec
- Turnstile checker — the same inspection this server exposes, in a browser
- Turnstile error index
MIT.
SolveGate MCP questions
How do I add SolveGate MCP to Claude Code?
Run claude mcp add --env 'SOLVEGATE_API_KEY=<YOUR_SOLVEGATE_API_KEY>' solvegate-mcp -- npx -y solvegate-mcp in your terminal. Add --scope user to make it available in every project.
How do I add SolveGate MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does the server require an API key to work?
No, the inspect_page tool works without an account, allowing you to see what the server does before signing up.
Can this server solve reCAPTCHA or hCaptcha?
No, the server is specifically designed for Cloudflare Turnstile and does not support reCAPTCHA or hCaptcha.
What happens if a solve attempt times out?
Because solving is asynchronous, a timeout will leave you with a solve ID that you can retrieve using the get_solve tool.
How can I tell if I am using a sandbox key?
An sk_test_ key will return a mode of 'sandbox', which indicates the token will not clear a real gate.