Mastra CAPTCHAソルバー統合：実践的なMCPガイド

要約

• Mastra の MCPClient は、ローカルの CAPTCHA ソルバー・プロセスを起動し、stdio 経由でそのツール群を検出できます。
• listTools() は、例のサーバーキーに対して capsolver_get_supported_captchas のような名前空間付きツール名を返します。
• 言語モデルを関与させたり、有料の CAPTCHA タスクを送信する前に、必ずケイパビリティクエリを直接実行します。
• 検出されたあらゆるケイパビリティを自動で紐づけるのではなく、エージェントが必要とするツールだけを選択します。
• 単体のチェックが終わったら MCP クライアントを閉じ、ソルバーの結果とブラウザワークフロー完了を区別します。

Mastra CAPTCHA ソルバー統合は、TypeScript アプリケーションに対して検証チェックポイント用の明確なツール境界を与えます。ブラウザワークフローはチャレンジの前後で何をすべきか既に知っている一方で、エージェントはチャレンジ操作を要求するためのサポートされた方法を必要とします。MCP は、ソルバーの基礎 API に別のラッパーを追加することなく、そのケイパビリティを接続します。

この例では、CapSolver がローカルサーバーを提供します。本ガイドでは、実際の Mastra クライアントを使ってツールを検出し、サポートされているタイプのクエリを実行します。そのうえで、エージェントに適切なサブセットを紐づける方法と、ツールレスポンスと完了した Web タスクとを区別して保持する方法を説明します。この例はローカル統合チェックであり、サードパーティの Web サイトや有料 CAPTCHA は不要です。

Mastra アプリケーションのどこに CAPTCHA ツールが位置づくか

CAPTCHA ツールは、認可されたアプリケーションワークフロー内の既知のチャレンジステップに位置づきます。Mastra はエージェントに公開されるツールを調整し、ソルバーは特定の操作を実行し、ブラウザもしくはアプリケーションコードは、その結果を利用するステップを所有します。

オーナー管理のフォームテストを行う QA サービスを考えてみましょう。テストはデータを用意し、サポートされたチャレンジに到達しています。ソルバー操作は関連する解答を提供できますが、テストは依然としてフォームを正しく送信し、期待される確認結果をチェックしなければなりません。エージェントは、非空のツールレスポンスを受け取ったという理由だけで成功を報告すべきではありません。

Mastra プロジェクトはフレームワークを提供しており、そのMCP 接続ガイドではここで使用するクライアントインターフェースを説明しています。これは直接的な MCP 接続であり、ソルバーがすべての Mastra 製品やホスティングされた統合カタログにおけるネイティブプロバイダーであることを意味するものではありません。

小さなローカル統合プロジェクトの準備

各コンポーネントが明示的な依存関係セットを持つように、ローカルの Node.js プロジェクトと Python 環境を準備します。この例は Node.js 24.16.0、Python 3.12.14、@mastra/mcp 2.4.1、capsolver-mcp 0.1.3 で実行されました。選択した Mastra パッケージは Node.js 22.13.0 以降を必要とし、テスト済みの Node.js 24 ランタイムを使用することで、古いランタイムとのミスマッチを避けられます。

macOS または Linux 上の新しいプロジェクトディレクトリで次を実行します:

npm init -y
npm install @mastra/mcp@2.4.1
python3 -m venv py
py/bin/python -m pip install capsolver-mcp==0.1.3

以下の .mjs ファイルは、Node の ES モジュールサポートを利用しています。サーバーパスはスクリプトを実行するディレクトリからの相対パスで解決されるため、py を含むプロジェクトルートから実行してください。Python 環境が別の場所にある場合は、シェルの PATH 上で最初に見つかった Python に依存するのではなく、そのパスを変更してください。

この直接ツールチェックには、モデルの認証情報は不要です。モデル駆動のレスポンスには、モデルプロバイダーの認証が必要です。有料 CAPTCHA 操作には、適切なソルバーアカウントの認証情報とタスクパラメータが必要です。この分離により、モデルの挙動やブラウザの状態、アカウント課金を導入する前に、インストール上の問題を診断できます。

MCPClient を接続してサポートされている CAPTCHA タイプをクエリする

インストール済みの Python プロセスに MCPClient を接続し、ツールを検出し、ケイパビリティクエリを実行します。次をプロジェクトディレクトリに mastra-check.mjs として保存します:

import { MCPClient } from '@mastra/mcp';
import { resolve } from 'node:path';

const client = new MCPClient({
  id: 'captcha-setup-check',
  servers: {
    capsolver: {
      command: resolve('py/bin/python'),
      args: ['-m', 'capsolver_mcp'],
      env: { CAPSOLVER_API_KEY: process.env.CAPSOLVER_API_KEY || '' },
    },
  },
});

try {
  const tools = await client.listTools();
  console.log('TOOLS', Object.keys(tools));
  const capabilityTool = tools.capsolver_get_supported_captchas;
  if (!capabilityTool) throw new Error('Capability tool was not discovered');
  const result = await capabilityTool.execute({});
  console.log('CAPABILITIES', JSON.stringify(result, null, 2));
} finally {
  await client.disconnect();
  console.log('DISCONNECTED');
}

このアダプタは、公式の CapSolver MCP 起動インターフェース と Mastra のクライアントを組み合わせています。スクリプトはインストール済みパッケージに対して実行され、ケイパビリティ呼び出しと切断も含まれます。フェイクのサーバーレスポンスを構築したり、チャレンジを送信したりはしません。

同じプロジェクトディレクトリから実行します:

node mastra-check.mjs

テストされたリストには、capsolver_solve_captcha、capsolver_detect_captchas、capsolver_solve_on_page、capsolver_get_balance、capsolver_get_supported_captchas が含まれていました。ケイパビリティ呼び出しは次のような構造化された結果を返しました:

{
  "success": true,
  "registered_handlers": ["recaptcha", "cloudflare"],
  "captcha_types": ["reCaptchaV2", "reCaptchaV3", "cloudflare"]
}

この結果は、インストール済みパッケージの登録済みハンドラとタイプ値を示しています。これは、CapSolver の Web サイトに掲載されているすべてのプロダクトが、このパッケージバージョン経由で利用できることを意味するものではありません。また、クライアント閉鎖後に DISCONNECTED が出力されました。実行時には、これらの値の周囲に追加のサーバ診断行が含まれる場合があります。

エージェントにツールを紐づける前に名前を理解する

Mastra は、フラットなツールリストに設定済みサーバーキーで名前空間を付与します。ここでは capsolver がサーバーキーで get_supported_captchas がリモートツール名であり、返却オブジェクト内では capsolver_get_supported_captchas になります。

表示ラベルから推測するのではなく、返却されたキーを使用してください。サーバーエントリの名前を変更すると、コードが期待するキーも変わります。動作中の構成を大きなアプリケーションへ移行する際は、ルックアップやツール名を含むエージェント指示を再利用する前に、再度検出されたツールを確認してください。

MCPClient リファレンスには検出と接続ライフサイクルが記載されています。セットアップメモと一緒にパッケージバージョンを残しておきましょう。インストール済みバージョンに対しては、古いチュートリアルの呼び出しと現在のクライアントを組み合わせるのではなく、リファレンスからメソッド名をコピーしてください。

ジョブごとにツールのサブセットを選ぶ

エージェントが行う可能性のある作業に基づいてツールのサブセットを選びます。セットアップアシスタントには、ケイパビリティクエリだけで十分かもしれません。既にタスクパラメータを抽出しているワークフローには、トークン指向の解決ツールが必要になることがあります。ページ指向のワークフローは、異なるブラウザ依存関係とセッション要件を持ちます。

実際の Mastra エージェント用には、関連する検出エントリからツールオブジェクトを構成し、エージェントのドキュメントにある tools 設定を通じて渡します。エージェントがツールを呼び出せる間は MCP 接続を維持してください。このスタンドアロンスクリプトは、その唯一の仕事が 1 件のクエリだからこそ直ちに切断しています。このライフサイクルを変更せずに長時間稼働するエージェントへそのままコピーすると、接続が早すぎる段階で閉じられてしまいます。

直接クエリは、モデルにツール選択を委ねることなく、トランスポートとデータを可視化します。これが通ったら、通常のモデル認証情報とアプリケーションの権限ルールを用いて、エージェントによるツール選択を別途テストします。直接クエリの成功は、次のテストを切り分ける助けになるべきであり、それを置き換えるものではありません。

CapSolver ボーナスコードを利用する

自動化予算を今すぐブースト！
チャージ時にボーナスコード CAP26 を使用すると、すべてのリチャージに対して 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード で利用しましょう。

ツール結果をブラウザワークフローに接続する

ツール結果を、承認されたブラウザタスクを所有するコンポーネントに接続します。トークン指向とページ指向の結果は異なる扱いが必要なため、エージェントプロンプトを追加する前に、アプリケーションがどちらのインターフェースを使用するかを決めておきます。

コードが既にサポートされている CAPTCHA タイプとその必須パラメータを把握している場合、ソルビングツールはその構造化入力を受け取れます。ブラウザコードは、ドキュメントに記載された統合経路を通じて結果を適用し、アプリケーションの次の状態を観測する責任を持ち続けます。ツール呼び出しの成功は、これらのチェックの代わりにはなりません。

サーバーのブラウザベースツールを使用する場合は、ドキュメントに記載の依存関係をインストールし、セッションがどのように生成されるかを確認してください。ローカルコマンドを通じて起動されるサービスは別プロセスです。別のブラウザの開いているタブ、フォーム状態、認証済みセッションなどを自動的には継承しません。core SDK は、既に制御しているページオブジェクトと直接連携する必要がある場合に評価すべき、別のインターフェースです。

QA レコードには、到達したステージ、選択されたツール、ツール結果、最終的なアプリケーションアサーションを記録できます。これらのフィールドは異なる疑問に答えます。接続失敗は統合に関する問題であり、タスクエラーはソルバーリクエストに関するもの、確認状態の欠如はアプリケーションワークフローに関するものです。ログやユーザー向けステータスメッセージでは、これらの区別を保持してください。

発生したステージごとに失敗を処理する

エージェントにワークフロー全体の再試行を許可する前に、失敗したステージを処理します。多くの初期統合失敗には、実用的なチェックポイントが少数存在します:

API コール は、より大きなユーザータスクが未完了のままであっても、あるレイヤーでは成功することがあります。実際に観測した結果を報告してください。「ツール接続は確立された」はセットアップ中には有用ですが、「フォーム送信済み」はフォームの結果が観測されたときにのみ主張できます。

実際のチャレンジ操作については、再試行回数を制限してください。設定診断のためだけに新しい有料タスクを生成しないようにしましょう。動作するケイパビリティクエリは、ローカル接続を切り分ける、より安価な手段を提供します。サーバーコマンドが見つからない場合には、公式 MCP インストールガイド も役立ちます。

有用な診断コンテキストを保持する

パッケージバージョン、設定済みサーバーキー、操作名、プロセスが正常起動したかどうかを保持してください。これらの詳細は、アカウントキーやブラウザセッション全体を共有することなく、別の開発者が失敗を再現するのに役立ちます。この例では、名前空間の欠如とサーバー起動失敗とは、どちらも最初はツールが見つからないように見えても、必要な対処が異なります。

タスクがワーカー間で移動する場合は、そのアプリケーションレコードを、この診断クライアントのライフタイムから分離して保持してください。ローカルオブジェクトの欠如を、エージェントが自動的に新しい有料リクエストへと変換しないようにします。前回の操作がまだ有効かどうかを判断するのはアプリケーション側であり、その判断なしに再試行を許可すべきではありません。

最初の統合は小さく保つ

最初の統合は、1 つの許可されたワークフローと狭いツールセットに絞って行いましょう。この例では、クライアントが実サービスを検出し、非ソルビングのケイパビリティクエリを実行し、構造化データを受け取り、切断できることを確認しています。モデルが正しいツールを選択したり、有料 CAPTCHA とブラウザタスクが完了したと主張しているわけではありません。

その基盤から、アプリケーションが必要とするチャレンジ操作を接続し、その受け入れテストを追加します。CapSolver はソルバーのケイパビリティを提供し、Mastra アプリケーション側が、それをいつ使用すべきか、何を完了した作業と見なすかを決定します。その後のエンドツーエンドテストの前に、CapSolver ダッシュボード で認証情報を準備してください。

FAQ

Q: LLM の API キーなしで接続テストはできますか？

はい。この例は、Mastra の MCP クライアントを通じて検出されたツールを直接呼び出します。言語モデルにレスポンス生成やツール選択を依頼してはいません。

Q: ケイパビリティクエリは実際の CAPTCHA 解決ですか？

いいえ。インストール済みサービスからの登録ハンドラと CAPTCHA タイプ情報を返すだけであり、有料の解決やブラウザページの状態を検証するものではありません。

Q: ツール名が capsolver_get_supported_captchas なのはなぜですか？

プレフィックスは capsolver というサーバーキーに由来します。Mastra はフラットなリスト内で、リモートツール名にその名前空間を付加します。

Q: 検出されたすべてのツールをエージェントで使えるようにすべきですか？

いいえ。エージェントに割り当てられたジョブに必要なケイパビリティだけを選択し、その選択と実行をアプリケーションの権限・ワークフローに照らしてテストしてください。

Q: disconnect はいつ呼ぶべきですか？

クライアント経由で追加の呼び出しが不要になったときに呼びます。単発の診断では finally 内で閉じて構いませんが、稼働中のエージェントでは、ツール利用期間を通して接続を維持する必要があります。

Q: これは本番ブラウザワークフローが動く証拠になりますか？

いいえ。ローカルのクライアント・サーバ統合とクエリを検証するだけです。本番では依然として、有効な認証情報、サポートされたタスクパラメータ、適切なブラウザ状態、そしてエンドツーエンドのアプリケーションチェックが必要です。