起動できない、またはタスクを解決できない MCP サーバーを修正する

MCP ホストが動作するマシンの端末で、付属のランチャーを実行してください。条件を揃えて再現するには、Node.js 22 とそれに同梱された npx を使用し、別途インストールされた古いランチャーが使われていないことを確認してください。

node --version
npx --yes --package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz solvethree-mcp
# The process waits for JSON-RPC on stdin. Silence is not a failed startup.
# Use the MCP host to initialize and list tools. Press Ctrl-C to stop this check.
# Never paste an API key or proxy password into troubleshooting logs.

何も出力せずにプロセスが起動したままでも、停止しているとは限りません。これはローカルの stdio サーバーで、標準入力からの MCP JSON-RPC メッセージを待機しています。MCP ホストを使って接続を初期化し、ツール一覧を取得してください。実行ファイルを単独で実行しても、このハンドシェイクは行われません。

終了する場合は、まず起動エラーを確認してください。実行ファイルが見つからないエラーは、インストールまたは PATH の問題を示します。パッケージのダウンロードエラーは、タスクの解決前に発生するものです。どちらも、API キー、プロキシ、サイトプロファイルに問題がある証拠にはなりません。

solvethree をリモート HTTP エンドポイントではなく、ローカルの stdio サーバーとして登録してください。ホストは、ランチャーの例に示された引数で npx を実行する必要があります。ホスト型の MCP エンドポイントはありません。

ホストが npx を見つけられない。

ホストの PATH と端末の PATH を比較してください。デスクトップアプリケーションは、シェルの設定を継承しない場合があります。

試してみましょう： npx が含まれるディレクトリをホストで利用できるようにするか、ローカルで動作した実行ファイルと同じものの絶対パスを設定してください。

ホストが異なるバージョンの Node.js または npx を実行している。

端末で使われているバージョンだけでなく、ホストが実際にどの実行ファイルを参照しているかを確認してください。

試してみましょう： 動作確認済みのインストール先をホストに指定してください。ホストの環境を変更した後は、ホストを再起動してください。

初期化時に、不正な JSON または予期しない出力が報告される。

標準出力に書き込まれているシェルのバナー、ラッパーのメッセージ、デバッグ出力がないか確認してください。

試してみましょう： 標準出力は MCP JSON-RPC 専用にしてください。診断出力は標準エラー出力に送ってください。そうすれば、ホストはプロトコル通信として扱うことなく収集できます。

起動中にホストが待機を打ち切る。

起動ログを確認し、起動に時間がかかっているのか、プロセスがすでに終了しているのかを見分けてください。

試してみましょう： Codex 形式の設定では、ドキュメントに記載されている startup_timeout_sec の値 60 を使用してください。待機時間を延ばしても、実行ファイルの欠落や明示的な起動エラーは解消しません。

solvethree のツールが登録されていないとホストに表示される。

サーバーの初期化が完了していることを確認し、検出で返されたツールを確認してください。

試してみましょう： サーバーの登録を修正するか、再接続してツールを再検出してください。ツールの欠落は、API 認証エラーや解決の失敗ではありません。

サーバーは solvethree_capabilities、solvethree_create_recaptcha、solvethree_create_kasada、solvethree_create_tmpt、solvethree_get_task を公開します。検出に成功しても、ホストがこれらの名前のいずれかを呼び出せない場合は、タスクリクエストを送信する前に、その不一致を解消してください。

1. 1.

   ホストプロセスの環境を確認する

   ホスト環境を通じて SOLVETHREE_API_KEY と SOLVETHREE_PROXY を渡してください。別のターミナルで変数をエクスポートしても、ホストがそれを読み取れるとは限りません。Codex 形式の設定では、env_vars に両方の名前を含める必要があります。このパススルーリスト自体は値を設定しません。キーやプロキシの認証情報を出力せずに、変数が存在するか確認してください。

2. 2.

   ツールが実際に読み取る場所でプロキシを確認する

   solvethree_create_recaptcha は、使用する単一のプロキシを SOLVETHREE_PROXY から読み取ります。環境変数の値がない場合、ツールに proxy 引数を追加して解決しようとしないでください。プロキシ URL は HTTP または HTTPS を使用し、パス、クエリ、フラグメントを含めないでください。

3. 3.

   reCAPTCHA のサイトプロファイルを確認する

   API キーで識別されるワークスペースには、要求するサイトと reCAPTCHA タイプに対応する有効なプロファイルが必要です。キャプチャアクションも確認してください。汎用的なホスト名プロファイルが 1 つあっても、すべてのアクションに対応できるとは限りません。タスクで site と action を指定しても、プロファイルは作成されません。コンソールのサイトプロファイルページ、またはプロファイル設定ガイドで対応してください。

4. 4.

   ツールの入力を確認する

   solvethree_create_recaptcha には、ホスト名としての site、action、requestId を指定してください。recaptchaType は省略可能で、デフォルトは enterprise-v3 です。site にページ URL を指定したり、API の他のタスクタイプをこのツールに追加したりしないでください。

機能の検出では、認証やプロキシへのアクセスはテストされません。capabilities の呼び出しに成功した後の認証エラーやリクエスト検証エラーは、ランチャーではなく解決リクエストの問題です。レスポンスを成功したタスクのペイロードとして扱う前に、成功以外の HTTP レスポンスを処理してください。

ホストのタイムアウトはタスクのステータスではありません。Codex 形式の設定では tool_timeout_sec に 100 を使用しますが、レスポンスを受け取れなくても、タスクの作成に失敗したとは限りません。各作成ツールには requestId が必要で、作成されるタスクは最大 1 件です。

タスク ID を受け取っている場合は、そのタスクを取得してください。受け取っていない場合は、同じ requestId で同じ作成リクエストを再送して、既存のタスクを取得してください。呼び出しがタイムアウトしただけで、新しい requestId を生成しないでください。同じ ID を再利用しながらタスクの入力を変更すると、競合が発生します。

タスクの準備ができたら、返されたブラウザ識別情報と成功時のプロキシを使って解決結果を送信してください。その後ウェブサイトがリクエストを拒否した場合は、MCP の起動ではなく、その送信内容を調査してください。解決データは非公開に保ってください。MCP ホストはこのデータを受け取ります。