solvegate-mcp

# solvegate-mcp

[![CI](https://github.com/SolveGate/solvegate-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SolveGate/solvegate-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/solvegate-mcp)](https://www.npmjs.com/package/solvegate-mcp)
[![Glama score](https://glama.ai/mcp/servers/SolveGate/solvegate-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SolveGate/solvegate-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

```bash
npx solvegate-mcp
```

Claude Desktop / any MCP client, in your config:

```json
{
  "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](https://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_page` says so by name instead of letting you find out
  from a `422`.
- **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 is
  `waf` rather than `turnstile`.
- **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](https://solvegate.io/legal) is the binding version, and
targets on the denylist return `403 forbidden_target` regardless of what any
agent asks for.

## Development

```bash
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](https://solvegate.io/docs)
- [OpenAPI spec](https://solvegate.io/openapi.json)
- [Turnstile checker](https://solvegate.io/tools/turnstile-checker) — the same
  inspection this server exposes, in a browser
- [Turnstile error index](https://solvegate.io/turnstile-errors)

MIT.