MCPでAIエージェントにCAPTCHA解決機能を追加する

公式の@solvethree/sdkダウンロードには、solvethree-mcp実行ファイルが含まれています。以下の設定では、npxを使い、指定のパッケージURLから実行します。入力するホスト型MCPエンドポイントはありません。

• MCPホストが動作する環境でnpxを利用できるようにしてください。
• ホスト環境でSOLVETHREE_API_KEYにワークスペースのAPIキーを設定します。ブラウザーコードやプロンプトには含めないでください。
• その環境でSOLVETHREE_PROXYを設定します。reCAPTCHAツールは、ツールリクエストではなく、この変数から単一のプロキシを読み取ります。

JSON形式のMCP設定を受け付けるホストでは、次のサーバーエントリを追加します。

{
  "mcpServers": {
    "solvethree": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz",
        "solvethree-mcp"
      ]
    }
  }
}

Codexでは、代わりに次のTOML設定を使用します。env_varsエントリは、ホスト環境から2つの変数を引き渡すもので、変数の値を設定するものではありません。

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

これらの環境変数を利用できる状態で、ホストを起動または再読み込みします。solvethree_capabilities、solvethree_create_recaptcha、solvethree_create_kasada、solvethree_create_tmpt、solvethree_get_taskが公開されていることを確認してください。

reCAPTCHAタスクを作成する前に、対象サイトのプロファイルを設定し、ワークスペースで有効になっていることを確認してください。MCP経由でホスト名とアクションを送信しても、そのプロファイルは作成されません。

solvethree_capabilitiesで利用可能な機能を確認します。reCAPTCHA v3 Enterpriseでは、次のリクエストでsolvethree_create_recaptchaを呼び出します。

{
  "site": "accounts.example.com",
  "action": "login",
  "requestId": "agent-login-001",
  "waitMs": 0
}

accounts.example.comを対象サイトに、loginをアプリケーションに必要なアクションに置き換えてください。この論理タスクのrequestIdを決め、リクエストとともに保持します。waitMsをゼロに設定した場合、この呼び出しで完了を待つのではなく、結果を別途取得します。

基盤となるタスクAPIでは任意のフィールドですが、MCPでの各作成呼び出しにはrequestIdが必須です。ASCIIの英字、数字、アンダースコア、ハイフンを1–64文字で使用してください。

1. 1.

   返されたタスクIDを保持

   タスクの作成は、結果の取得とは異なります。エージェントが同じタスクを取得できるよう、タスクIDを保存してください。

2. 2.

   solvethree_get_taskを呼び出す

   作成呼び出しで返されたタスクIDを使用します。ステータスがpendingまたはsolvingの場合は、後でタスクを再取得してください。どちらのステータスにも使用可能な解答は含まれません。

3. 3.

   終端ステータスを処理

   readyの場合は、ブラウザーまたはアプリケーションとの連携処理に解答を渡します。failedの場合は、errorCodeとerrorを確認し、そのタスクのポーリングを停止してください。

reCAPTCHAでは、ブラウザーまたはアプリケーションのリクエストを通じてsolution.tokenを送信します。そのリクエストのUser-Agentヘッダーとsec-ch-uaヘッダーを、返されたuserAgentとsecChUaから設定し、SOLVETHREE_PROXYに設定したプロキシを再利用してください。プロバイダーが送信元IPをローテーションする場合は、そのプロキシセッションを固定して維持します。

Kasada はヘッダーを返し、Ticketmaster TMPT は生の Cookie 値を返します。リクエストしたタスクに対応する出力を適用してください。これらの結果に互換性はありません。

MCP サーバーはブラウザーの操作やフォームへの入力を行いません。ホストが非公開の解決データを受け取り、アプリケーションが送信を行います。対象サイトの応答は別途確認してください。ready は solvethree が解決結果を生成したことを意味し、対象サイトが受け入れたことを意味するわけではありません。

接続がタイムアウトしても、タスクの作成に失敗したとは限りません。タスク ID を受け取っている場合は、そのタスクを取得してください。受け取っていない場合は、同じ requestId と変更していないタスク入力で同じ作成リクエストを再送し、既存のタスクを復旧してください。応答が失われたという理由だけで、新しい ID を生成しないでください。

リクエスト ID を異なるタスク入力で再利用すると競合します。タスク自体が失敗した場合は、変更内容を決める前にエラーを確認してください。無効な入力をやみくもに再送しても解決しません。リクエストエラーとタスクの失敗の違いについては、CAPTCHA API のエラーを参照してください。