solvegate-mcp

Un servidor MCP que le permite a un agente resolver Cloudflare Turnstile: comprobar si una página tiene uno y, si lo tiene, resolverlo.

Tres herramientas. Una de ellas no necesita clave.

Instalación

npx solvegate-mcp

Claude Desktop / cualquier cliente MCP, en tu configuración:

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

Deja fuera SOLVEGATE_API_KEY y inspect_page seguirá funcionando. Es una decisión deliberada: deberías poder ver qué hace el servidor antes de decidir si registrarte en algo.

Obtén una clave en solvegate.io. Una clave de sandbox sk_test_ gratuita no requiere tarjeta y devuelve un token determinista al instante: ideal para configurar esto, y nunca resuelve una barrera real.

Related MCP server: cloudscraper-mcp

Por qué existe inspect_page

El error más habitual con un servicio de resolución es llamarlo cuando deberías haber mirado antes. Tres casos cubren la mayoría de las ocasiones:

• La página contiene reCAPTCHA o hCaptcha, no Turnstile. Son productos distintos de proveedores diferentes. Este servidor no los resuelve, y SolveGate tampoco. inspect_page lo dice claramente en lugar de descubrirlo tú a través de un 422.

• Es un desafío WAF, no un widget. Una página de verificación intersticial de Cloudflare no tiene data-sitekey, porque el desafío pertenece a una regla de zona y no a un widget que tú insertes. No hay nada que leer de la página, y la barrera es waf, en lugar de turnstile.

• El sitekey se renderiza mediante script con la carga. En ese caso no está en el HTML entregado, y la herramienta lo indica en lugar de adivinar.

La inspección es gratuita, tarda alrededor de un segundo y, con frecuencia, es toda la repuesta necessaria.

Lo que no te dirá

El modo del widget. Los modos administrado, no interactivo e invisible se guardan en la configuración de la cuenta de Cloudflare que posee el sitekey. La página solo tiene la clave, así que ninguna herramienta puede leer el modo a partir del código fuente, incluida esta y cualquier cosa que diga lo contrario.

No influye la resolución: los tres modos desembocan en la misma solicitud. Un sitekey, una URL de página y un token como respuesta.

La única excepción son los cinco sitekeys de demostración documentados de Cloudflare, de quellos el propio Cloudflare publica el modo de widget. inspect_page los detecta, y encontrar uno en una página te dice algo útil: estás ante un entorno de staging, no de producción.

Configuración

La clave se lee del entorno y no es un argumento de herramienta; un argumento de herramienta es visible para el modelo y queda en las transcripciones.

Notas sobre el comportamiento

La resolución es asíncrona por debajo. solve_turnstile crea la resolución con async: true y la consulta, en lugar de mantener una conexión abierta durante todo el intento. Una llamada de herramienta de un agente tiene un tiempo de espera que no está bajo su control, y una resolución síncrona haría que una barrera lenta pareciera una herramienta sin respuesta. También implica que un tiempo de espera aquí te deja con un id de resolución: el error señala ese id, y get_solve lo o recupera en lugar de perder una resolución que ya se ha cobrado.

Los errores son resultados, no excepciones. Cada fallo vuelve como resultado isError que incluye el error.code de SolveGate: balance_empty, unknown_sitekey, rate_limited y forbidden_target. Un modelo puede trabajar con estos códigos. No puede sacar nada útil de una stack trace.

Los tokens son de un solo uso y de corta validez. expiresAt es una marca Unix en segundos. Una vez ver acumulado, Cloudflare deja de aceptar el token y el registro de la resolución es solo un registro. Solicita un token en el momento de querer usarlo.

Comprueba mode antes de confiar en un token. Una clave sk_test_ devuelve mode: "sandbox", y un token de sandbox no supera una barrera real. Este campo existe para que una clave de prueba en una configuración de producción falle en lugar de silenciosamente.

Uso aceptable

Resuelve solo contra las propiedades que poseas o que estén autorizadas para probar. Esto está pensado para pruebas de extremo a extremo que siguen fallando por un desafío, CI contra tu propio entorno de staging y supervisión sintética de tu producción. La política de uso aceptable es la versión vinculantes, y los objetivos de la lista de bloqueo devuelven 403 forbidden_target independientemente de lo que pide un agente.

Desarrollo

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

Las pruebas se ejecutan sobre un transporte stdio real en lugar de llamar directamente a las devoluciones de llamada de las herramientas. Es a propósito: un esquemagrama de datos que rechaza el SDK al registrar, o una escritura inesperada en stdout, que corrompe el transporte, ya que stdout es el transporte, solo aparece cuando aprovechable argumento que de verdad habla el protocolo con él.

Enlaces

• Referencia de la API SolveGate

• Especificación OpenAPI

• Comprobador de Turnstile : la misma inspección que expone este servidor, en el navegador

• Índice de errores de Turnstile

MIT.