MCP CAPTCHAソルバー：Cloudflare Turnstile 統合ガイド

TL;DR

• MCP CAPTCHAツールは、ブラウザエラーごとに自動実行するのではなく、認証チェックの後に配置する必要があります。
• CapSolverは、互換性のあるクライアント向けにMCPサービスをドキュメント化し、タスク作成と結果取得を基盤とするタスクライフサイクルを提供しています。
• Turnstileワークフローには、ページURLとサイトキーに加え、ドキュメント化されたタスクで必要な場合のブラウザセッションの一貫性が必要です。
• 返されたトークンを短期間のシークレットとして扱い、ログに記録しないでください。リトライの回数を制限し、ページの結果を検証してください。
• 技術的な能力は、プライベート、制限、機密、または未承認のデータへのアクセス権を保証しません。

MCP統合で可能になること

MCP Cloudflare Turnstileソルバーの統合により、AIクライアントは認証されたワークフロー内でチャレンジを処理するための制御されたツール境界を取得します。CapSolverはcapsolver-mcpをMCP互換クライアントのオプションとしてドキュメント化しており、そのAIエージェントガイドではローカル検出とフィルバック、およびサービスによる認識が分離されています。

有用な設計目標は、無制限のブラウジングではなく、復元です。エージェントはブロックされたステップを検出、範囲を確認し、ドキュメント化されたパラメータをまとめ、1つのツールを呼び出し、返された結果を検証し、継続またはレビューのために停止します。

前提条件とポリシーのゲート

ツールに接続する前に、承認されたドメイン、許可されたアクション、最大試行回数、ログルール、および人間によるレビューの条件を定義してください。クライアントは、ホストでサポートされているMCPランタイムと、シークレットストレージに保存されたCapSolverの資格情報も必要です。実際の資格情報はプロンプトやソースコード管理に含めないでください。

Cloudflareは、Turnstileウィジェットがサーバーサイドで検証されるトークンを生成することを説明しています。したがって、トークンだけではビジネスアクションが成功した証拠とはなりません。防御者側のモデルについては、CloudflareのTurnstile実装フローとTurnstile概要を参照してください。

MCPサービスに接続する

公式CapSolver Core SDKドキュメントに示されている現在のパッケージと構成を使用してください。正確なインストールコマンドは、パッケージの場所やサポートされているクライアントが変更される可能性があるため、意図的にここでは複製されていません。インストール後、クライアントが期待されるCapSolverツールをリストしていることを確認し、共有環境に構成を配置する前にクリーンに切断してください。

この記事では認証されたハンドシェイクを実行していません。このテストは開示された前提条件のギャップのままです。ライブ証拠としてツールの出力を提示していません。

CapSolverボーナスコードを引き換える

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際にボーナスコードCAP26を使用すると、すべてのチャージで5%のボーナスが追加されます。制限はありません。
CapSolverダッシュボードで今すぐ引き換えてください

エージェントループにツールを接続する

モデルに向けた契約を狭く保ちます。入力は承認されたページとチャレンジパラメータを識別する必要があります。出力はステータスと暗号化された結果を公開し、クレデンシャルをエコーしないでください。エージェントは決してサイトキー、タスクタイプ、または成功応答を発明してはなりません。

堅牢なループには5つの状態があります：detected、authorized、submitted、verified、およびstopped。ブラウザが期待されるページ状態を観測した後のみverifiedに移動してください。タスクが処理中の場合、CapSolverタスクライフサイクルに基づいて固定予算内でポーリングしてください。繰り返しエラーが発生した場合は、無限リトライループを作成せず、停止してください。

エラーの境界と観測可能性

構成エラーとチャレンジの失敗を分離してください。パラメータが不足している場合は、どのAPIコールも実行する前に失敗してください。サービスエラーは相関IDを保持する必要がありますが、クレデンシャルと返されたトークンはマスキングしてください。ブラウザの不一致の場合、その証拠に機密データが含まれていない場合にのみスクリーンショットまたはDOMアサーションを保持してください。

プロトコルの文脈については、公式MCP紹介がクライアントサーバー境界を説明しています。この境界はポリシーの実行に役立ちます。要求が許可リストに該当しない限り、エージェントはツールへのアクセスを拒否されるためです。

公式SDKからのMCP CAPTCHAソルバーのセットアップ

CapSolverのMCPサービスは、直接のPython統合で使用される同じコアSDKに基づいて構築されています。ブラウザ対応のパッケージは、隔離された環境でのみインストールしてください。その後、MCPクライアントの構成を通じてツールを公開してください。現在の公式パッケージはPyPIではなくGitHubからインストールされています：

python -m venv .venv
source .venv/bin/activate
pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

CAPSOLVER_API_KEYをホストの承認済みシークレットストアに保存してください。MCP JSON、記事、ソースリポジトリ、またはモデルが見える引数に値を置かないでください。ツールはページ参照または構造化されたチャレンジ情報を受け入れるべきであり、ホストはモデルコンテキストの外で資格情報を注入する必要があります。

严格的ツールポリシーを使用してください

MCPホストは、ディスパッチの前にポリシーオブジェクトを評価できます。以下の構成は、アプリケーションの例であり、CapSolver APIペイロードではありません：

{
  "allowedDomains": ["staging.example.com"],
  "allowedCaptchaTypes": ["cloudflare"],
  "maxAttempts": 2,
  "timeoutSeconds": 120,
  "requireHumanReviewForStateChange": true,
  "logToken": false
}

起動時に構成ローダーでこのファイルを検証してください。未知のフィールドを拒否し、タイプミスが制御を無効にしないようにしてください。

直接Turnstile APIフォールバック

アプリケーションがすでにサイトURLとサイトキーを知っている場合、CapSolverはAntiTurnstileTaskProxyLessをドキュメント化しています。必要なタスクフィールドはtype、websiteURL、websiteKeyです。metadata.actionとmetadata.cdataは、ウィジェットに存在する場合にオプションです。

import os
import time
import requests

API = "https://api.capsolver.com"

def solve_turnstile(website_url: str, website_key: str) -> str:
    client_key = os.environ["CAPSOLVER_API_KEY"]
    create = requests.post(
        f"{API}/createTask",
        json={
            "clientKey": client_key,
            "task": {
                "type": "AntiTurnstileTaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=30,
    ).json()
    if create.get("errorId"):
        raise RuntimeError(create.get("errorDescription", "createTask failed"))

    task_id = create["taskId"]
    deadline = time.monotonic() + 120
    while time.monotonic() < deadline:
        result = requests.post(
            f"{API}/getTaskResult",
            json={"clientKey": client_key, "taskId": task_id},
            timeout=30,
        ).json()
        if result.get("errorId"):
            raise RuntimeError(result.get("errorDescription", "getTaskResult failed"))
        if result.get("status") == "ready":
            return result["solution"]["token"]
        time.sleep(3)
    raise TimeoutError("Turnstile task exceeded the polling budget")

このコードは構文チェックされていますが、この記事では資格情報を実行していません。返されたトークンは、同じ認証されたワークフロー内でのみ適用してください。その後、結果のページ状態を検証してください。

観察可能な復元経路を構築する

MCPの最良の復元経路は、監査可能な大きさである必要があります。1つの承認されたドメイン、1つの文書化されたタスクタイプ、1つのリトライ予算、1つのページアサーションのみを含めます。失敗の理由がログで示された後のみカバレッジを拡大してください。運用サポートを計画する際には、CapSolver FAQと関連する自動化記事を参照してください。

認証されたエージェントワークフローでは、CapSolverは認識コンポーネントとなることができます。アプリケーションは、権限、セッション処理、検証、安全な停止を担当します。

FAQ

Q: MCP自体がCloudflare Turnstileを解決しますか？

いいえ。MCPはツール接続パターンを定義しています。設定されたCapSolverサービスが認識を実行し、クライアントが検出、パラメータ、結果の使用を制御します。

Q: エージェントはどのウェブサイトでもツールを呼び出せますか？

いいえ。自動化が許可されているサイトとアクションに呼び出しを制限し、権限が不明な場合は停止してください。

Q: ワークフローが成功したことを証明するものは何ですか？

ブラウザが検証後の期待されるページ状態を観測したことが証明されます。返されたトークンだけでは不十分です。

Q: トークンはログに記録すべきですか？

いいえ。クレデンシャルと返されたトークンをシークレットとして扱い、ロギングするのはマスキングされた運用メタデータのみを記録してください。