Proofpoint Essentials

Proofpoint Essentials MCP サーバー

Proofpoint Essentials API 用の Model Context Protocol (MCP) サーバーです。 AI アシスタントが、組織、ドメイン、ユーザー、ライセンス、機能、サブスクリプションパッケージ、メールフローのレポートなど、MSP のマルチテナント環境におけるメールセキュリティを管理できるようにします。

これは Proofpoint TAP とは別の製品／API です（TAP の脅威インテリジェンス、 隔離、URL 防御については proofpoint-mcp を参照してください）。Essentials は Proofpoint の SMB／MSP 向けメールセキュリティ製品であり、独自のベース URL、認証モデル、組織管理機能を備えています。

WYRE AI MCP フリートの一部です — MSP スタック向けの AI 統合ツール群が拡大しています。

インストール

npm install @wyre-ai/proofpoint-essentials-mcp

設定

.env.example をコピーし、以下の変数を設定します。

変数	必須	説明
PROOFPOINT_ESSENTIALS_USERNAME	stdio および AUTH_MODE=env の場合	組織管理者のユーザー名（X-User ヘッダーとして送信）
PROOFPOINT_ESSENTIALS_PASSWORD	stdio および AUTH_MODE=env の場合	組織管理者のパスワード（X-Password ヘッダーとして送信）
PROOFPOINT_ESSENTIALS_REGION	いいえ	リージョンのサブドメイン。例：us1 または eu1（デフォルト：us1）
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。gateway モードでは、各 /mcp リクエストに X-Proofpoint-Essentials-Username と X-Proofpoint-Essentials-Password が必要です（X-Proofpoint-Essentials-Region は任意）。PROOFPOINT_ESSENTIALS_* へのフォールバックは行いません。env は S2S 認証が成功した後にのみ、これらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレット。空の場合、または既知のプレースホルダー（changeme、secret、placeholder、your-s2s-secret、replace-with-a-real-secret、および src/index.ts にある同じリスト）の場合、HTTP サーバーはエラーをログに記録し、ゼロ以外の終了コードで終了します。未設定の場合、Compose は起動しません。実際の値をコミットしないでください。プロセスがこの値をログに記録することはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	ローカル開発で CONDUIT_S2S_SECRET なしに HTTP を起動する場合にのみ、正確に 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S を省略して、127.0.0.1 のみで待ち受けます。より広い範囲を指定する MCP_HTTP_HOST は上書きされます。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレス。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合は、0.0.0.0 を含め、この値が適用されます。コンテナーイメージでは 0.0.0.0 が設定されます。シークレットがない場合、リスナーは 127.0.0.1 のみで待ち受けます。
MCP_HTTP_PORT	いいえ	HTTP ポート。デフォルトは 8080 です。

この API で認証できるのは組織管理者アカウントのみです。エンドユーザーアカウントは認証できません。

/health と /healthz は認証なしで利用でき、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。ヘッダーがないか無効な場合、ベンダーの認証情報を読み取る前に 401 を返します。

このヘッダーはシークレットのコピーではなく、HMAC による証明です。

t=<unix seconds>,v1=<hex hmac-sha256>

<hex hmac-sha256> は、ASCII 文字列 t=<unix seconds>（同じ t= プレフィックスと同じ 10 進数のタイムスタンプ）の HMAC-SHA256 です。CONDUIT_S2S_SECRET をキーとして使用し、小文字の 16 進数でエンコードします。タイムスタンプはサーバーの時計との差が 300 秒以内である必要があります。

import { createHmac } from "node:crypto";

const secret = process.env.CONDUIT_S2S_SECRET;
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", secret).update(`t=${t}`).digest("hex");
const xGatewayS2s = `t=${t},v1=${v1}`;

AUTH_MODE=gateway の場合、/mcp には X-Proofpoint-Essentials-Username と X-Proofpoint-Essentials-Password も必要です。各リクエストでは、これらのヘッダーのみを認証情報の取得元として使用します。

await fetch("http://127.0.0.1:8080/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    "x-gateway-s2s": xGatewayS2s,
    "x-proofpoint-essentials-username": "[email protected]",
    "x-proofpoint-essentials-password": "org-admin-password",
    "x-proofpoint-essentials-region": "us1",
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
});

使用方法

Claude Desktop での実行

Claude Desktop の claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "proofpoint-essentials-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/proofpoint-essentials-mcp"],
      "env": {
        "PROOFPOINT_ESSENTIALS_USERNAME": "your-username",
        "PROOFPOINT_ESSENTIALS_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code（CLI）での実行

claude mcp add proofpoint-essentials-mcp \
  -e PROOFPOINT_ESSENTIALS_USERNAME=your-value \
  -e PROOFPOINT_ESSENTIALS_PASSWORD=your-value \
  -- npx -y @wyre-ai/proofpoint-essentials-mcp

Docker

イメージはコンテナ内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、デフォルトで AUTH_MODE=gateway を使用します。ポートをループバックアドレスに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、Proofpoint Essentials の認証情報は各リクエストで X-Proofpoint-Essentials-* ヘッダーとして渡されます。イメージは環境変数から認証情報を読み込みません。

docker build --platform linux/amd64 --build-arg GITHUB_TOKEN=$(gh auth token) -t proofpoint-essentials-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  proofpoint-essentials-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE=gateway を設定して 127.0.0.1:8080:8080 を公開します。また、PROOFPOINT_ESSENTIALS_* 変数は渡しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、PROOFPOINT_ESSENTIALS_USERNAME と PROOFPOINT_ESSENTIALS_PASSWORD を使用します。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e PROOFPOINT_ESSENTIALS_USERNAME=your-value \
  -e PROOFPOINT_ESSENTIALS_PASSWORD=your-value \
  -e PROOFPOINT_ESSENTIALS_REGION=us1 \
  -p 127.0.0.1:8080:8080 \
  proofpoint-essentials-mcp

シークレットを使用しないローカル HTTP は、開発用途に限られます。127.0.0.1 にバインドされ、警告がログに記録されます。ループバック以外の MCP_HTTP_HOST は 127.0.0.1 に上書きされます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

利用可能なツール

Proofpoint Essentials は MSP 向けのマルチテナント API です。組織／ドメイン／ユーザーを対象とするすべてのツールでは、呼び出しごとに対象顧客組織のドメインを引数として指定します（認証情報は単一の組織に限定されません）。

組織

• proofpoint_essentials_org_get — 組織データとそのドメインを取得します
• proofpoint_essentials_org_set_active — 組織を有効化／無効化します ⚠ 影響大
• proofpoint_essentials_org_delete — 組織を削除します ⚠ 破壊的操作、取り消し不可

ドメイン

• proofpoint_essentials_domains_list
• proofpoint_essentials_domains_create — パラメーター：orgDomain、空でない domains: string[]。各名前は Domain オブジェクト {name} として送信されます。戻り値は { summary: { requested, returned, succeeded, failed, unconfirmed }, results } です。返された項目がすべて成功し、未確認の項目（不足項目を含む）がない場合に限り、結果には項目ごとの生データが含まれます。requested は送信した件数です（返された件数がこれを上回る場合のみ、返された件数に引き上げられます）。応答にない項目は未確認として数えられます。失敗した項目があると isError が設定されます。失敗または未確認の項目がある場合、results は不要なフィールドを省いた項目ごとのリスト { index, outcome, status, code, message } になります。成功した項目は作成済みのため、再試行しないでください。
• proofpoint_essentials_domains_update ⚠ 影響大
• proofpoint_essentials_domains_delete ⚠ 破壊的操作、取り消し不可

ユーザー

• proofpoint_essentials_users_list
• proofpoint_essentials_users_get
• proofpoint_essentials_users_create — パラメーター：orgDomain、必須の primary_email と、任意の firstname、surname、type、is_active、send_welcome_email、alias_emails を含む空でない users[]。ユーザーは、User オブジェクトの配列をそのまま Proofpoint に送信します。戻り値は { summary: { requested, returned, succeeded, failed, unconfirmed }, results } です。返された項目がすべて成功し、未確認の項目（不足項目を含む）がない場合に限り、結果には項目ごとの生データが含まれます。requested は送信した件数です（返された件数がこれを上回る場合のみ、返された件数に引き上げられます）。応答にない項目は未確認として数えられます。失敗した項目があると isError が設定されます。失敗または未確認の項目がある場合、results は不要なフィールドを省いた項目ごとのリスト { index, outcome, status, code, message } になります。成功した項目は作成済みのため、再試行しないでください。作成時には、応答専用のフィールド（uid、password、creation_date、last_update、last_login）は無視されます。
• proofpoint_essentials_users_update ⚠ 影響大
• proofpoint_essentials_users_delete ⚠ 破壊的操作、取り消し不可

作成時のシリアライズと結果の正規化に関する修正には @wyre-ai/node-proofpoint-essentials >= 1.0.2 が必要です。このパッケージはこれに依存しています。

エンドポイントの検出

• proofpoint_essentials_endpoint_discover — 顧客ドメインをホストしているリージョンを特定します

機能／ライセンス／パッケージ

• proofpoint_essentials_features_get / proofpoint_essentials_features_update ⚠ 高影響
• proofpoint_essentials_licensing_get / proofpoint_essentials_licensing_update ⚠ 高影響
• proofpoint_essentials_package_update ⚠ 高影響

レポート

• proofpoint_essentials_reporting_get — 受信／送信メールのフローメトリクス

トークン

• proofpoint_essentials_token_create — Odin ベースの SSO トークンを発行します

破壊的なツールの実行には、明示的な確認が必要です。対話型 MCP クライアントでは エリシテーションを通じて確認を求められます。非対話型の呼び出し元（WYRE ゲートウェイなど）は confirm_destructive_action: true を渡す必要があり、渡さない場合はブロックされます。

開発

git clone https://github.com/WYRE-AI/proofpoint-essentials-mcp.git
cd proofpoint-essentials-mcp
npm install
npm run build
npm test
npm run smoke   # requires a prior `npm run build`

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md をご覧いただくか、変更について話し合うために イシューを作成してください。

エラーのマスキング

エラーテキストおよびクリーンアップ済みのバッチ結果メッセージでは、サポート対象のエンコードされた @ 形式（%40、%2540、@、@、@、リテラルの \u0040、 全角の ＠）、@ の前後に空白がある形式、引用符で囲まれたローカル部を含め、メールアドレスをマスキングします。ドメインツールのエラーおよびクリーンアップ済みのドメイン作成メッセージでは、ホスト名のみの文字列もマスキングします。ベンダーのエラーボディは statusCode とスカラーの code メタデータに縮小され、その他のベンダーフィールドは省略されます。各エラーテキストまたはクリーンアップ済みの項目ごとのメッセージは、マスキング後に Unicode コードポイント 300 文字を上限とします（集約バッチ JSON は上限の対象外です）。成功が確認された結果では、生データが保持されます。これは対象を絞ったマスキングであり、一般的な PII の削除ではありません。

ライセンス

Apache License, Version 2.0 に基づいてライセンスされています。詳細は LICENSE をご覧ください。