solvegate-mcp

solvegate-mcp

エージェントがCloudflare Turnstileに対処できるMCPサーバーです。ページにTurnstileがあるか確認し、あれば解除します。

ツールは3つあります。そのうち1つはアカウント不要です。

ツール	機能	キーが必要
inspect_page	URLを取得し、Cloudflare Turnstileの有無、サイトキー、レンダリング方法、data-*設定、およびページ全体に表示されるWAFチャレンジかウィジェットかを報告します	いいえ
solve_turnstile	TurnstileまたはTurnstile WAFチャレンジを解除し、トークンを返します	はい
get_solve	IDで解決結果を取得します。無料で、再課金されません	はい

インストール

npx solvegate-mcp

Claude Desktop／任意のMCPクライアントでは、設定に次の内容を追加します。

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

SOLVEGATE_API_KEYを省略しても、inspect_pageは引き続き使えます。これは意図的な仕様です。何かに登録するかを決める前に、サーバーの動作を確認できるようにしています。

キーはsolvegate.ioで取得できます。無料のsk_test_サンドボックスキーはカード不要で、決定論的なトークンを即座に返します。接続確認に適しており、実際のゲートを解除することはありません。

inspect_pageがある理由

ソルバーで最もよくある誤りは、先に確認すべきところで呼び出してしまうことです。よくあるケースは次の3つです。

• ページにあるのがTurnstileではなく、reCAPTCHAまたはhCaptchaです。 これらは異なるベンダーの別製品です。このサーバーもSolveGateもこれらを解決できません。inspect_pageなら、422で初めて気づくのではなく、その旨を明示してくれます。
• ウィジェットではなく、WAFチャレンジです。 Cloudflareのページ全体に表示されるインタースティシャルにはdata-sitekeyがありません。チャレンジは埋め込みウィジェットではなくゾーンルールに属するためです。ページから読み取れる情報はなく、ゲートの種類はturnstileではなくwafです。
• サイトキーが読み込み後にスクリプトによってレンダリングされます。 その場合、配信されたHTMLには含まれておらず、ツールは推測せずにその旨を伝えます。

確認は無料で、約1秒で完了し、多くの場合、それだけで答えが得られます。

確認できないこと

ウィジェットのモードです。 Managed、非インタラクティブ、Invisibleの設定は、サイトキーを所有するCloudflareアカウント内のウィジェットに保存されています。ページに含まれるのはキーだけなので、このツールを含め、ソースからモードを読み取れるツールはありません。読み取れるとうたっているものも同様です。

解決には影響しません。3つのモードはいずれも同じリクエスト、つまりサイトキーとページURLを渡してトークンを受け取る仕組みです。

例外は、Cloudflareが公開している5つの公式ダミーサイトキーです。Cloudflare自身がウィジェットの種類を公開しています。inspect_pageはそれらを報告するため、ページ上で見つかれば有益な手がかりになります。つまり、本番環境ではなくステージング環境のビルドを確認しているということです。

設定

変数	デフォルト	機能
SOLVEGATE_API_KEY	—	キーです。サンドボックスにはsk_test_、実際のゲートにはsk_live_を使います。
SOLVEGATE_BASE_URL	https://api.solvegate.io	APIのベースURLです。
SOLVEGATE_SITE_URL	https://solvegate.io	inspect_pageの実行先です。
SOLVEGATE_TIMEOUT_MS	30000	リクエストごとのタイムアウトです。
SOLVEGATE_MAX_WAIT_MS	60000	保留中の解決をsolve_turnstileが待つ時間です。

キーは環境変数から読み込まれ、ツールの引数にはなりません。ツールの引数はモデルから見えるため、トランスクリプトにも記録されます。

動作に関する注意点

内部では非同期で処理されます。 solve_turnstile は async: true で解決処理を開始し、試行全体の間接続を開いたままにするのではなく、ポーリングします。エージェントのツール呼び出しには、エージェントが制御できないタイムアウトがあり、同期処理では時間のかかるゲートが応答しないツールのように見えてしまいます。また、ここでタイムアウトしても解決 ID が残ります。エラーに ID が記載され、get_solve で処理を再開できるため、すでに課金された解決処理が失われることはありません。

エラーは例外ではなく結果として返されます。 すべての失敗は、SolveGate 固有の error.code（balance_empty、unknown_sitekey、rate_limited、forbidden_target）を含む isError 結果として返されます。モデルはそれらに基づいて動作できます。スタックトレースから有用な動作をすることはできません。

トークンは一度だけ使用でき、有効期間も短いです。 expiresAt は Unix 秒です。有効期限を過ぎると、Cloudflare はトークンを受け付けなくなり、解決レコードは単なる記録になります。送信するタイミングでトークンをリクエストしてください。

トークンを信頼する前に mode を確認してください。 sk_test_ キーでは mode: "sandbox" が返され、サンドボックスのトークンでは実際のゲートを通過できません。このフィールドがあることで、本番環境の設定にテストキーが混入した場合、気付かれないままではなく、はっきりエラーになります。

許容される利用

自分が所有している、またはテストを許可されているプロパティに対してのみ解決してください。これは、チャレンジで失敗し続けるエンドツーエンドテスト、自分のステージング環境に対する CI、自分の本番環境の合成監視を目的としています。 許容される利用ポリシーが拘束力を持つ正式な規定であり、拒否リストに登録されたターゲットは、エージェントの要求内容にかかわらず 403 forbidden_target を返します。

開発

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

テストではツールのコールバックを直接呼び出すのではなく、実際の stdio トランスポートを使用します。これは意図的なものです。SDK が登録時に拒否するスキーマや、stdout への予期しない書き込みは、実際にプロトコルで通信させるまで発覚しません。stdout はトランスポートそのものなので、こうした問題はトランスポートを破損させます。

リンク

• SolveGate API リファレンス
• OpenAPI 仕様
• Turnstile チェッカー — このサーバーが提供するものと同じ検査をブラウザーで実行します
• Turnstile エラー一覧

MIT。