この記事で分かること

2026 年現在、エディタ内のチャットとは別に、Cursor SDK や付随する CLI からクラウド上の Agentをプログラムで起動する流れが増えています。検索クエリとしては「Cursor SDK」「タイムアウト」「Agent API」「MCP」「HTTPS_PROXY」などが並び、現場の症状はIDE では補助機能が動くのに、スクリプト実行だけが長時間待ったあと失敗するという形で現れやすいです。

本稿はデスクトップ向け Mihomo／Clash Meta 系 GUI のひとつである Clash Verge Rev を前提に、(1) ルール分流（Rule）で Agent API や関連ドメインを意図したノードへ送る、(2) MCP（Model Context Protocol）まわりでローカルとリモートが混ざるときの NO_PROXY の考え方、(3) ターミナルや子プロセスへ HTTPS_PROXY／HTTP_PROXY をどう渡すか——を一続きで整理します。エンドポイントはアップデートで変わりうるため、固定リストより Verge Rev のログと curl による実測を優先してください。エディタ画面中心の切り分けはCursor × Clash の拡張機能・AI 向け記事、OpenAI ルートの CLI はCodex 向けの記事と補い合えます。Clash Verge Rev チュートリアルで触れたポリシー名とログの見方もそのまま再利用できます。

検索意図と症状の対応：総タイムアウト／MCP 断

Cursor SDK から クラウド Agent を叩くケースでは、次のようなクリティカルパスが隠れやすく、ユーザーが入力しがちなキーワードと対応させて整理できます。

  • ジョブ全体が数十秒〜数分で切れる：Agent API が国境付近で DIRECT のまま残っている、SNI が途中機器で改変されている、Keep-Alive が古い経路に張り付いている、などTLS 以前または途中ホップの問題が混じります。
  • ツール呼び出しやスキーマ取得だけが不安定：MCP ではローカルの stdio／SSE と外向き地 HTTPS が短時間に交互に走るため、どちらか片方だけ プロキシ 設定が欠けると「一部のステップだけ失敗」に見えます。
  • 成功と失敗が交互に出る（フラッピング）：複数ターミナルが別々の .zshrc を読んでいる、CI ランナーだけ HTTPS_PROXY が空、旧プロセスが古い DNS キャッシュを掴んでいる——といった状態の二重化が典型です。

いずれも「ネットワーク全体が死んだ」より、HTTPS クライアントが期待したプロキシチェーンに乗っていない比率が高いです。Clash Verge Rev のログで一行ずつ追えることは、説明責任のある運用では大きな利点になります。

Cursor SDK と IDE 表示層でズレが生まれる理由

同じマシンでも、Electron ベースの UI と、Cursor SDK が内部で起こす子プロセスでは、参照するプロキシ設定が一致しないことがあります。GUI は OS のシステムプロキシや独自プロファイルを先に見る一方、Node／Go／Rust の HTTP スタックは HTTPS_PROXY と NO_PROXY に強く依存します。

このズレは「クラウド Agent の総タイムアウト」としてユーザーに見えやすいです。ブラウザ検証では問題ないのに CLI だけETIMEDOUTになるパターンは、まず Shell で env | grep -i proxy を確認し、API 分流のログと突き合わせるのが早いです。

MCP と Agent API を同じ頭で扱うときの注意

MCP は、ローカルに立てたサーバ（stdio）と、外向きのメタデータ取得や認可フローが同居します。ルール分流では次の二層に分けると事故が減ります。

  • 内向き（そのマシン上）：127.0.0.1／localhost は意図的に DIRECT。誤ってプロキシへ流すと往復が増え、レイテンシだけが跳ね上がります。
  • 外向き（プロバイダ側）：ログに出たドメインを DOMAIN または妥当な DOMAIN-SUFFIX で PROXY に寄せ、MATCH より上へ置きます。

Agent API と MCP を同時に扱うワークフローでは、「外向きドメインのリスト」と「ローカル例外のリスト」を分けてノートに残すと、チーム共有やインシデント後の振り返りが楽になります。

Rule を軸に、TUN は補助として使う

ルール分流は、社内 Git や決済ドメインを DIRECT に残しつつ、Agent API を PROXY へ送る第一選択です。YAML の順序とログを突き合わせれば、「どのホストがどのポリシーへ落ちたか」をテキストで説明できます。

TUN はカーネル近傍でトラフィックをキャプチャし、プロキシ変数を無視するバイナリでも一度 Mihomo 側へ引き込める強力な手段ですが、ゼロトラスト VPN や別製品の仮想 NIC と競合しやすいです。実務的には、(1) Rule とシステムプロキシで足りるか試す、(2) 特定バイナリだけの問題なら限定的に TUN、(3) 常時フル TUN は最後の手段、の順が安全です。

Clash Verge Rev では「システムプロキシをセット」「TUN を開始」が別操作のため、ブラウザだけ整備されターミナルが裸、という分岐に注意してください。

HTTPS_PROXY を中心にしたターミナル向け環境変数

Cursor SDK を cron、direnv、CI、ローカルシェルから叩く場合、GUI よりも環境変数の比重大きくなります。典型的には次を揃えます。

  • HTTPS_PROXY：HTTPS への CONNECT が主用途なら最優先。
  • HTTP_PROXY：リダイレクト先行の HTTP フェーズで参照されます。
  • ALL_PROXY：単一変数しか読まないツールへの保険（無視されることもあります）。
  • NO_PROXY：localhost、127.0.0.1、社内 SSO を除外し、MCP のローカル待受とのループを防ぎます。

値は多くの場合 http://127.0.0.1:<mixed-port> で足り、TLS は CONNECT でトンネルします。書き場所の例は ~/.zshrc、~/.bashrc、リポジトリの .envrc、あるいは検証時のみのコマンド前置き HTTPS_PROXY=... cursor-agent … です（ポートは各自のプロファイルに合わせて読み替え）。

ルールへ載せるホストはログ実測を優先

固定リストは保守コストが高く、サービス側変更で簡単に陳腐化します。検索で繰り返し見かける型としては次を出発点にし、実名はログで上書きしてください。

  • Cursor 系プロダクト：cursor.com／cursor.sh 周辺のサブドメイン。証明書名とホストが一致していることをログで確認します。
  • モデルや外部 API：設定で選んだプロバイダに応じて api.openai.com など（社内規程と契約を確認のうえ利用）。
  • 認証・CDN・補助サービス：コンソールや SDK が内部的に追加するホストは、エラー直後の一行ログから拾うのが最短です。

Agent API のエラーメッセージに出るホスト名は、本文の説明よりログ列挙のほうが信頼できます。GPT 系や他社 API を併用するなら、それぞれの記事型ガイドとルールセットの整合も見てください。

TIP：一度だけGlobal に近いプリセットで SDK ジョブを走らせ、症状が消えるかを見てください。消えるなら DIRECT 落ちのルール順が本命で、MATCH より上へ個別 DOMAIN を挿入しやすいです。

ルール記述例（ポリシー名は各プロファイルに合わせる）

以下は Mihomo／Clash Meta 互換の説明用スニペットです。PROXY を利用中のポリシーグループ名へ置換し、既存の MATCH より上に置いてください。

# Example rules snippet — replace PROXY with your policy group name
rules:
  - DOMAIN-SUFFIX,cursor.com,PROXY
  - DOMAIN-SUFFIX,cursor.sh,PROXY
  # Add provider API hosts from Verge Rev logs above MATCH

広すぎる DOMAIN-KEYWORD は誤爆しやすいので、ログに出た実名を DOMAIN で足す運用を推奨します。

ステップ：Cursor SDK のクラウド Agent を安定させるまで

  1. Clash Verge Rev が期待するプロファイルで起動済みであり、mihomo が待ち受けていることを確認します。
  2. ブラウザで同じノードを用いた海外サイト疎通を見て、問題がSDK／CLI 限定かを切り分けます。
  3. 失敗再現直後のログからホスト名を拾い、API 分流ルールを追加します。fake-ip とルール種別の組み合わせでマッチがズレていないかも見ます。
  4. システムプロキシだけでは足りない場合、新しいターミナルで HTTPS_PROXY と HTTP_PROXY を export してから Cursor SDK を起動します。
  5. 問題の URL へ curl -vI を送り、Clash 側で意図したチェーンに乗ったかを確認します。
  6. 個別バイナリが依然として直結する場合は TUN を試す前に、HTTPS インスペクションや別 VPN のスタック競合を疑います。

検証のコツ：MCP 込みで状態を一元化する

「設定した HTTPS_PROXY」が統合ターミナルに届かないときは、非ログインシェル、タスクランナーのサンドボックス、コンテナのネット命名空間などを疑います。

  • 同一ホストで curl と SDK が別結果：curl は変数が効いており SDK が無視しているなら、そのランタイム版のドキュメントで代理関連の環境名やフラグを確認します。
  • IPv6 と IPv4 の分裂：curl -4 でのみ通るときは DNS か経路が二系統化しています。
  • 社内 Split DNS：機密系は NO_PROXY に残し、外部 Agent API だけ PROXY —— の二段にすると開発者端末での事故が減ります。
注意：コードやログをクラウド Agent へ送る操作は、利用規約と会社の情報セキュリティポリシーに触れることがあります。ネットワークが安定しても、アップロード可否は別判断です。
ダウンロードページへ

トラブルシューティング

症状：curl は成功するが Cursor SDK だけタイムアウト

想定原因：ランタイムが環境変数を読まず、別設定ファイルやラッパーで直結している。

対処：公式ドキュメントのプロキシ項目を確認し、起動スクリプトで明示的に export。複数バージョンのパス競合も疑います。

症状：PROXY に乗っているのに極端に遅い

想定原因：ノード輻輳、HTTP/3 フォールバック、DNS の迂回失敗。

対処：地域の違うアウトバウンドへ切替、DNS をプロファイル内で固定、検査プロキシを一時的に外して差分確認。

症状：MCP だけローカル接続が不安定

想定原因：ローカル待受が NO_PROXY に入っていない、または誤ってプロキシへ流している。

対処：127.0.0.1 系を除外し、外向きだけルールを厚くする。セキュリティソフトのローカルループ制限も確認します。

よくある質問

クラウド Agent だけがタイムアウトするのはなぜですか？

UI 層と CLI 層で参照するプロキシ設定が異なるためです。Clash Verge Rev のログで DIRECT 漏れを潰し、Shell に HTTPS_PROXY を揃えてください。

MCP の外向き通信も同じルールで足りますか？

外向きドメインはログの実名を載せ、ローカル待受は除外する二段構成が安全です。固定リスト任せにしないでください。

HTTPS_PROXY はどこに書けばよいですか？

常時なら Shell 設定や direnv、単発検証ならコマンド前置きのみ。副作用を限定するのがポイントです。

単一製品 VPN との比較で見える Clash の利点

ワンタップ型の商用 VPN は初期導入が楽でも、ドメイン単位の細かな例外やログでの逆引きには向きにくいことがあります。開発者ワークステーションでは、Git だけ直結できない、Agent API だけ別経路で詰まる、といった摩擦が出やすいです。Clash 系は本文のとおりルール分流とログで API 分流を説明できるため、Cursor SDK と社内サービスを同じ端末上で両立させるほうが現実的になります。

フロントエンドは好みで選べますが、Verge Rev はプロファイル編集とログ監視が近接しており、CLI 中心の検証とも相性がよいです。大手 VPN の「すべて同じ出口」に比べ、詰まった場所をドメイン粒度でほどける点が長期的な運用リスクを下げやすいです。

無料で Clash を入手し、SDK 向けの分流と検証を試す →