superagent

Superagent

コーディングエージェントが外部コンテキストを取り込む前にチェックするコンテキストガードレールを設定したり、MCP 経由でエージェントを Superagent に接続したり、署名付き Webhook を設定したりできます。認証情報を保護し、リモートでの操作、課金を伴う操作、破壊的な操作、ポリシーを変更する操作によってユーザーを不意に驚かせないようにしてください。

Superagent MCP は認証が必要なリモートサービスです。ユーザーが明示的に求めない限り、接続したり、データを送信したり、MCP クライアントの設定を変更したりしないでください。

意図に応じて設定リクエストを振り分けます。

• コンテキストガードレールの設定またはコーディングエージェントのフック：コンテキストガードレールの統合に従ってください。MCP に接続するだけでは、取り込み前のチェックは適用されません。
• Superagent MCP の接続またはトラブルシューティング：MCP 設定ワークフローに従ってください。
• 署名付きイベント配信：Webhook の設定に従ってください。

MCP 設定ワークフロー

1. MCP クライアントと、ユーザーが新規接続、トラブルシューティング、既存の接続に対する操作のどれを希望しているかを確認します。
2. 設定の場合は、Superagent Settingsで組織 API キーを作成するようユーザーに案内します。キーをチャットに貼り付けるよう求めてはいけません。
3. ユーザーのシェルまたはシステム環境にキーを SUPERAGENT_API_KEY として保存します。リポジトリ、追跡対象の .env ファイル、コマンド出力、応答には決して含めないでください。
4. 正確なエンドポイント https://www.superagent.sh/mcp を使用してください。ドメインのみの場合はリダイレクトされ、一部の MCP クライアントはリダイレクトされた POST リクエストに失敗します。
5. クライアントの設定を編集したり、設定コマンドを実行したりする前に、変更案を提示して承認を得ます。
6. 製品に対する操作を試みる前に、クライアントが接続し、Superagent のツールを利用できることを確認します。

組織 API キーでは、組織全体にアクセスできます。エージェントで使う場合は、専用の取り消し可能なキーを優先し、漏えいした場合は直ちに取り消してください。

クライアント設定

Cursor

このサーバーを mcp.json に追加します。リモートサーバーは envFile を読み取れないため、Cursor の起動環境に SUPERAGENT_API_KEY が存在している必要があります。

{
  "mcpServers": {
    "superagent": {
      "url": "https://www.superagent.sh/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUPERAGENT_API_KEY}"
      }
    }
  }
}

Claude Code

SUPERAGENT_API_KEY がエクスポートされていることを確認してから、次の設定を提案します。

claude mcp add --transport http --scope user superagent https://www.superagent.sh/mcp \
  --header "Authorization: Bearer $SUPERAGENT_API_KEY"

Claude Code で /mcp を実行し、接続を確認します。

Codex CLI

次の設定を ~/.codex/config.toml に追加します。機能フラグはすべての [mcp_servers.*] ブロックより前に記述する必要があります。トークンの設定には、トークン自体ではなく環境変数名を指定します。

experimental_use_rmcp_client = true

[mcp_servers.superagent]
url = "https://www.superagent.sh/mcp"
bearer_token_env_var = "SUPERAGENT_API_KEY"

Codex を起動する前に変数をエクスポートし、その後 /mcp を使って確認します。

その他の MCP クライアント

ストリーミング可能な HTTP を次のように設定します。

• URL：https://www.superagent.sh/mcp
• ヘッダー：Authorization: Bearer $SUPERAGENT_API_KEY

トークンは追跡対象の設定ファイルではなく、クライアントがサポートするシークレットストアまたは環境変数ストアに保存してください。

Superagent の操作

固定のツール一覧があると想定せず、接続先サーバーで利用可能なツールを確認してください。ユーザーのリクエストを次の機能グループに対応付けます。

• 検出結果：検出結果の一覧表示と確認、手動トリアージの更新、自動トリアージの依頼。
• レポート：リポジトリ、Web アプリ、エージェント、パッケージのレポートの一覧表示または確認。新しいレポートの作成は、確認を得てから行います。
• コントリビューターの信頼性：キャッシュ済みの結果を取得するか、スキャンを開始して状況を確認します。
• コンテキストガードレール：エージェントが取り込む前に、Web ページ、メール、ファイル、スキル、公開 MCP リポジトリをスコアリングします。
• ランタイムガードレール：エンドポイントクライアント、グループ、ルール、組み込みのルールモード、アラートを管理します。

質問に答えるために必要な、最小限の読み取り専用呼び出しを優先します。結果を要約し、ユーザーが後続の操作で必要とする識別子は保持してください。非同期操作では、返されたステータスまたは識別子を伝え、短い間隔でのポーリングは避けます。

コンテキストガードレールの統合

単発のスキャンと適用を区別してください。

• 「この URL、ファイル、メール、スキル、または MCP リポジトリをスキャン／チェックして」と依頼された場合は、対応する MCP ツールを使用します。
• 「Context Guardrails を追加／有効化／統合して」と依頼された場合は、エージェントがコンテキストを使用する前に、ツール境界でチェックを実施するようインストールします。SKILL.md、AGENTS.md、ルール、システムプロンプトはガイダンスであり、強制的な制御ではありません。

次のセットアップワークフローを使用します。

1. 保護するコンテキストの取得元、セットアップをプロジェクト単位とグローバルのどちらにするか、スキャナーが利用できない場合にアクションをブロックするかを確認します。セキュリティが重要なワークフローではフェイルクローズを推奨し、組織の API キーを使用する制御にはユーザーレベルまたは管理対象のフックを推奨します。プロジェクトフックは信頼できるリポジトリでのみ使用します。
2. クライアントの現在のフック設定と、サポートされているイベントを確認します。既存の設定に統合し、設定全体を置き換えないでください。
3. コンテキストを導入するアクションを、使用前に制御します。ページには web-fetch と curl／wget のアクション、公開ファイルにはダウンロードアクション、スキルにはスキルのインストール、MCP リポジトリには MCP の追加／インストール設定、メールには受信メッセージのラッパーを使用します。後続のすべての MCP ツール呼び出しをリポジトリスキャンとして扱わないでください。
4. 選択した取得元ごとに、最も限定的なクライアントの実行前境界を対応付けます。
   • Cursor：preToolUse、beforeShellExecution、または beforeMCPExecution。
   • Claude Code：WebFetch、Bash、Skill、または関連する MCP ツールに対応付けた PreToolUse。
   • Codex CLI：サポート対象のローカルツールおよび MCP ツール向けの PreToolUse。ホスト型の WebSearch はフックできないため、完全にカバーできると主張せず、そのギャップを明示します。
   • その他のクライアント：同等の実行前ツールフック、ラッパー、ミドルウェア、または承認済みラッパーと組み合わせた強制ルール。
5. 正確なフック、ヘルパー、パス、スコープ、判定ポリシー、障害時の動作、既知のカバレッジのギャップを提示します。ファイルの書き込み、クライアント設定の変更、Superagent へのテスト対象の送信を行う前に、承認を得ます。
6. 強制フックには、SUPERAGENT_API_KEY を使用して Context Guardrails REST API を呼び出す、小規模なローカルヘルパーをインストールします。一部のクライアントは MCP ベースのフックハンドラーに対応していますが、スキャンツールの結果がクライアント固有の許可／拒否判定に自動的に変換されるわけではなく、MCP エラーによってフェイルオープンする場合があります。MCP は対話型スキャンに直接使用し、クライアントを横断する強制制御のアダプターとしては使用しません。キーは環境内に保持し、ヘルパーやフック設定には決して記載しません。リポジトリ内のコードでひそかに置き換えられないよう、ユーザーが管理するリポジトリ外のヘルパーを優先し、絶対パスで参照します。
7. 許可される対象を1つ、ブロックされる対象または判定不能な対象を1つテストし、フックシステムで必要な場合はクライアントを再起動または再読み込みします。利用可能であればクライアントのフックインスペクターを使い、ヘルパーが警告を表示しただけでなく、実際にアクションがブロックされたことを確認します。

ヘルパーは、対応する /api/v1/context/* エンドポイントを呼び出す必要があります。

• Web ページの URL → GET /context/web_page/{identifier}
• 公開テキストまたは PDF の URL → POST /context/file
• 未加工の RFC 822 メール → POST /context/email
• skills.sh または公開 GitHub スキル → POST /context/skill
• 公開 GitHub MCP リポジトリ → POST /context/mcp

スキルと MCP のスキャンは公開 GitHub の対象のみをサポートし、アクティブな Superagent Security GitHub App のインストールが必要です。これらのフック経路が強制されていると主張する前に、この前提条件を確認します。エージェントのライフサイクルフックと、スキャン対象のコンテンツ内で見つかったパッケージ、Git、その他のインストールフックを区別します。後者は脅威の兆候です。

公開 URL 用のファイルスキャナーを通じて、ローカルの非公開ファイルをアップロードしないでください。生のメールやその他のユーザーコンテンツを送信する前に、明示的な承認を得ます。パッケージおよび一般的なリポジトリのスキャンは Context Guardrails の対象となる取得元ではありません。パッケージには Superagent のサプライチェーンスキャンを、ソースリポジトリにはリポジトリレポートを使用します。古いパッケージインストールフックを移植し、Context Guardrails がパッケージをスキャンしたと主張しないでください。 執行可否を判断する際は、スコアヘッダーだけに頼らず、JSON レスポンスを解析してください。選択した許容レベルを一貫して適用してください。

• safe：許可します。
• caution：ユーザーが別のポリシーを明示的に選択していない限り、ユーザーによる確認を求めます。
• suspicious または dangerous：拒否します。
• pending_deep_scan: true、スキャン不能な結果、不正な形式のレスポンス、スキャナーのタイムアウト：未解決として扱い、承認済みの障害時ポリシーに従います。

詳細スキャンが保留中の間に、暫定的な識別スコアによって処理が暗黙に許可されることのないようにしてください。完了に十分なフックタイムアウトを設定して mode=full を要求するか、ブロックまたは確認を求めたうえで、非同期スキャンの完了後に再試行するようエージェントに伝えてください。再帰的なチェックを避けるため、Superagent スキャナー自体への呼び出しは、汎用 MCP ゲートの対象外にしてください。

フックの安全要件

あるクライアントの JSON レスポンスを別のクライアントにそのまま流用せず、インストールされているクライアントの現在のフックスキーマに従ってください。

• ツールマッチャーとコマンド述語は、範囲を絞り、アンカーを付けてください。広範なフックは遅延を増やし、バイパスや誤ったブロックを引き起こします。
• 標準入力は構造化 JSON として解析してください。eval、シェル補間、信頼できないツール入力からのコマンド文字列の組み立ては、決して使用しないでください。識別子は URL エンコードし、値は引用符で囲んだ引数またはリクエストボディとして渡してください。
• 標準出力には、クライアントが文書化している判定 JSON のみを出力し、診断情報は標準エラーに送ってください。不正な入力や出力は、選択した障害時ポリシーに基づいてセキュリティ上の障害として扱ってください。
• 接続タイムアウトと合計タイムアウトを明示した、上限付きの HTTPS リクエストを 1 回だけ使用してください。認証ヘッダー、生のメールアドレス、またはユーザーコンテンツを含むレスポンスボディをログに記録しないでください。
• クライアントの通常の権限システムが拒否するアクションを、フック設定で自動承認しないでください。Context Guardrails は制限の追加にのみ使用してください。

プラットフォームごとの障害時の動作を明示的に適用してください。

• Cursor： セキュリティフックは、failClosed: true が設定されていない限り、クラッシュ、タイムアウト、不正な JSON の場合にフェイルオープンします。強制適用する境界では、これを設定してください。permission: "ask" は preToolUse では強制されません。確認が必要な場合は、確認要求に対応する境界を使うか、明確な確認指示を添えて拒否してください。
• Claude Code： ハードブロックには、PreToolUse の拒否レスポンスまたは終了コード 2 を使用してください。タイムアウトしたコマンド、HTTP、または MCP ツールのフックは通常の権限フローを続行するため、タイムアウトだけではフェイルクローズになりません。多層防御として、通常の権限ルールも維持してください。
• Codex CLI： 文書化されている PreToolUse の拒否 JSON、または終了コード 2 を使用し、理由は標準エラーに出力してください。フィールドが無効な場合やフックが失敗した場合、ツール呼び出しが続行されることがあります。WebSearch などのホスト型ツールはフックの対象外です。

Webhook の設定

ユーザーが Superagent のイベントをエージェント、チケット管理システム、または修復ワークフローに配信したい場合は、Webhook を使用します。Webhook の宛先は、現在の MCP ツールではなく、組織レベルの Superagent Settingsで設定します。MCP 呼び出しによって Webhook が作成または変更されたと主張してはいけません。

設定する前に、次の手順を行います。

1. イベントを受信する公開 HTTPS エンドポイントと、必要なイベントタイプを尋ねます。
2. エンドポイントがリクエスト本文の生データを保持できること、速やかに2xxを返すこと、時間のかかる処理を非同期キューに移せることを確認します。
3. 提案する宛先名、URL、サブスクリプションを提示します。組織全体に適用される宛先を作成または変更するためにブラウザツールや別の認証済みインターフェースを使う前に、承認を得ます。

ユーザーをSettings → Webhooks → Add webhookの順に案内します。承認された宛先名と HTTPS URL を入力し、サブスクリプションを選択して保存し、署名シークレットをコピーします。シークレットは一度しか表示されません。ユーザーにチャットへ貼り付けるよう求めてはいけません。また、ソース管理、コマンド出力、ログ、レスポンスに含めてはいけません。受信側のシークレットマネージャーまたは環境に保存します。

サポートされているサブスクリプションは次のとおりです。

• report.startedおよびreport.finished
• finding.created、finding.triage_completed、およびfinding.accepted
• contributor_trust.finished
• agent.finding_createdおよびagent.action_blocked

受信側は次の要件を満たす必要があります。

• 署名シークレットを使用し、<X-Superagent-Timestamp>.<raw-json-body>に対する HMAC-SHA256 でX-Superagent-Signatureを検証する。
• タイミングセーフな処理で署名を比較する。
• X-Superagent-Event-Idまたはペイロードのidを使って配信を重複排除する。
• ネットワークエラー、408、429、5xxのレスポンスは再試行されるため、速やかに2xxを返す。

保存後、Settings からテストイベントを送信し、下流の自動化を有効にする前に、署名、重複排除、レスポンス経路を検証します。シークレットが漏えいした場合は、直ちに再生成し、受信側を更新します。

確認ゲート

次の操作を行う直前に、明示的な確認を得てください。

• レポートの作成または検出結果の自動トリアージの実行。これらの操作では組織のクレジットを消費するためです。
• 検出結果の完全な削除。
• Runtime Guardrails のクライアント、グループ、またはルールの作成、更新、割り当て、削除。
• 組み込みルールのモードの変更または復元。エンドポイントのポリシーが直ちに変更されるためです。
• 組織の Webhook 宛先またはそのイベントサブスクリプションの作成、変更、無効化、ローテーション、削除。
• ユーザーがリモート分析を事前に許可していない宛先への送信、または許可していない内容の送信。

確認を求める際は、操作、対象、結果を正確に伝えてください。ツールのアノテーションは参考情報であり、このゲートの代わりにはなりません。

トラブルシューティング

• 401 invalid_token：キーが存在して有効であり、Authorization: Bearer ...として送信されていることを確認します。
• superagent.sh/mcpでの404または接続失敗：https://www.superagent.sh/mcpに切り替えます。
• サーバーに接続できてもツールが表示されない：プロキシが認証ヘッダーを削除していないことを確認します。
• Codex サーバーを利用できない：すべての MCP サーバーブロックより上にexperimental_use_rmcp_client = trueを配置し、bearer_token_env_varに変数名が含まれていることを確認します。
• 429：サーバーのRetry-Afterの間隔を待ちます。過度に再試行してはいけません。

ドキュメント

• MCP サーバー
• API の概要
• 設定と API キー
• Webhook
• 検出結果
• レッドチームレポート
• コンテキストガードレール
• コンテキストガードレール API
• Cursor フック
• Claude Code フック
• Codex CLI フック