Proofpoint Essentials

io.github.WYRE-AI由 GitHub 帳號 WYRE-AI 發布v1.1.1更新於 Nov 21, 2026

MCP server for Proofpoint Essentials -- MSP org, domain, user, licensing, and reporting management.

概覽

AI 產生的概覽

面向 Proofpoint Essentials 郵件安全 API 的 MCP 伺服器,讓助理管理 MSP 組織、網域、使用者、授權與郵件流量報表。

可以做什麼
  • 取得組織資料與其網域,啟用、停用或刪除組織,增刪組織層級的黑名單與白名單項目
  • 列出、建立、更新與刪除客戶網域
  • 列出、查詢、建立、更新與刪除使用者,並調整個別使用者的黑名單與白名單
  • 解析客戶網域所屬的區域
  • 讀取與更新功能、授權與訂閱方案
  • 讀取 inbound 與 outbound 郵件流量指標,並簽發 SSO 權杖
適用情境
適合 MSP 或 IT 管理員讓助理處理 Proofpoint Essentials 租戶的日常管理:開通網域與使用者、調整寄件者名單、查看授權狀況、取得郵件流量報表,而不必開啟主控台。
執行需求
以 stdio 方式在本機執行(npm 套件或容器映像)。需要組織管理員使用者名稱與密碼,透過 PROOFPOINT_ESSENTIALS_USERNAME 與 PROOFPOINT_ESSENTIALS_PASSWORD 提供,另可選區域如 us1 或 eu1。HTTP 模式還需 CONDUIT_S2S_SECRET,閘道模式則要求每次請求附上憑證標頭。終端使用者帳號無法通過驗證。
安裝前請注意
憑證為組織管理員層級且未限定單一客戶,每次呼叫都可能涉及任一租戶。許多工具標示為高影響或破壞性:刪除組織、網域與使用者無法復原;加入白名單會讓郵件繞過垃圾郵件過濾;移除黑名單項目會重新放行寄件者。破壞性工具需明確確認。寄件者名單的 PATCH 語意尚未在真實帳號上驗證,沒有公共後綴檢查,並行修改為後寫覆蓋。請勿提交 CONDUIT_S2S_SECRET。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Proofpoint Essentials,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Proofpoint Essentials MCP Server

[License] [Node.js]

A Model Context Protocol (MCP) server for the Proofpoint Essentials API. Enables AI assistants to manage MSP-multi-tenant email security: organizations, domains, users, licensing, features, subscription packages, and email flow reporting.

This is a distinct product/API from Proofpoint TAP (see proofpoint-mcp for TAP threat intelligence, quarantine, and URL defense) — Essentials is Proofpoint's SMB/MSP email-security product, with its own base URL, auth model, and org-management surface.

Part of the WYRE AI MCP fleet — a growing suite of AI integrations for the MSP stack.

Installation

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

Configuration

Copy .env.example and set the variables below.

VariableRequiredDescription
PROOFPOINT_ESSENTIALS_USERNAMEFor stdio and AUTH_MODE=envOrg-administrator username (sent as the X-User header)
PROOFPOINT_ESSENTIALS_PASSWORDFor stdio and AUTH_MODE=envOrg-administrator password (sent as the X-Password header)
PROOFPOINT_ESSENTIALS_REGIONNoRegion subdomain, e.g. us1 or eu1 (default: us1)
MCP_TRANSPORTNostdio (default) or http
AUTH_MODENogateway (Docker image and Compose default) or env. Gateway mode requires X-Proofpoint-Essentials-Username and X-Proofpoint-Essentials-Password on each /mcp request (X-Proofpoint-Essentials-Region is optional) and never falls back to PROOFPOINT_ESSENTIALS_*. env uses those variables only after S2S auth succeeds.
CONDUIT_S2S_SECRETYes for HTTPService-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder (changeme, secret, placeholder, your-s2s-secret, replace-with-a-real-secret, and the same list in src/index.ts). Compose will not start when it is unset. Never commit a real value. The process never logs it.
MCP_ALLOW_INSECURE_DEVNoSet to exactly 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, skips X-Gateway-S2S, and listens on 127.0.0.1 only. A wider MCP_HTTP_HOST is overridden. A known placeholder secret is still refused.
MCP_HTTP_HOSTNoBind address when MCP_TRANSPORT=http. Defaults to 127.0.0.1. A configured CONDUIT_S2S_SECRET honors this value, including 0.0.0.0. The container image sets 0.0.0.0. Without a secret, the listener is 127.0.0.1 only.
MCP_HTTP_PORTNoHTTP port. Defaults to 8080.

Only organization-administrator accounts can authenticate against this API; end-user accounts cannot.

/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. A missing or invalid header returns 401 before any vendor credential is read.

The header is an HMAC proof, not a copy of the secret:

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

<hex hmac-sha256> is HMAC-SHA256 of the ASCII string t=<unix seconds> (the same t= prefix and the same decimal timestamp), keyed with CONDUIT_S2S_SECRET, encoded as lowercase hex. The timestamp must be within 300 seconds of the server clock.

js
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}`;

In AUTH_MODE=gateway, /mcp also requires X-Proofpoint-Essentials-Username and X-Proofpoint-Essentials-Password. Those headers are the only credential source for that request.

js
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" }),});

Usage

Running with Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

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

Running with Claude Code (CLI)

bash
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

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode, Proofpoint Essentials credentials arrive on each request as X-Proofpoint-Essentials-* headers; the image does not read them from the environment.

bash
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 refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and passes no PROOFPOINT_ESSENTIALS_* variables:

bash
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses PROOFPOINT_ESSENTIALS_USERNAME and PROOFPOINT_ESSENTIALS_PASSWORD:

bash
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

Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST is overridden to 127.0.0.1:

bash
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Available Tools

Proofpoint Essentials is an MSP multi-tenant API — every org/domain/user-scoped tool takes the target customer organization's domain as a per-call argument (credentials are not scoped to a single org). Arguments that become part of an upstream URL path (orgDomain, domain, and the user email for update, delete and sender-list tools) are rejected when they contain whitespace, control characters, /, \, ? or #, or are exactly . or ... A user email used as a path segment must also be shaped like an email address: a local part, an @, then a domain.

Organizations

  • proofpoint_essentials_org_get — get org data and its domains
  • proofpoint_essentials_org_set_active — activate/deactivate an org ⚠ high-impact
  • proofpoint_essentials_org_delete — delete an org ⚠ destructive, irreversible
  • proofpoint_essentials_org_block_list_add — add entries to the org block list
  • proofpoint_essentials_org_block_list_remove — remove entries from the org block list ⚠ high-impact
  • proofpoint_essentials_org_allow_list_add — add entries to the org allow list ⚠ high-impact
  • proofpoint_essentials_org_allow_list_remove — remove entries from the org allow list ⚠ high-impact

Domains

  • proofpoint_essentials_domains_list
  • proofpoint_essentials_domains_create — params: orgDomain, non-empty domains: string[]. Each name is sent as a Domain object {name}; returns { summary: { requested, returned, succeeded, failed, unconfirmed }, results } with raw per-item results only when every returned item succeeded and none are unconfirmed, including missing items. Requested is the submitted count (raised to returned only on over-return); missing response items count as unconfirmed. Any failed item sets isError. Any failure or unconfirmed item makes results a cleaned per-item list { index, outcome, status, code, message } with other fields omitted; succeeded items are created and must not be retried.
  • proofpoint_essentials_domains_update ⚠ high-impact
  • proofpoint_essentials_domains_delete ⚠ destructive, irreversible

Users

  • proofpoint_essentials_users_list
  • proofpoint_essentials_users_get
  • proofpoint_essentials_users_create — params: orgDomain, non-empty users[] with required primary_email and optional firstname, surname, type, is_active, send_welcome_email, alias_emails. Users are sent to Proofpoint as a bare array of User objects; returns { summary: { requested, returned, succeeded, failed, unconfirmed }, results } with raw per-item results only when every returned item succeeded and none are unconfirmed, including missing items. Requested is the submitted count (raised to returned only on over-return); missing response items count as unconfirmed. Any failed item sets isError. Any failure or unconfirmed item makes results a cleaned per-item list { index, outcome, status, code, message } with other fields omitted; succeeded items are created and must not be retried. Response-only fields (uid, password, creation_date, last_update, last_login) are ignored on create.
  • proofpoint_essentials_users_update ⚠ high-impact — always reads the existing user (matched by primary_email) and merges on every update, also when type is supplied, then sends the merged record back in full because the PUT may replace the whole record. It refuses, with no PUT, when the record cannot be read or has no account type to keep (to avoid resetting the account to End User). data must not be empty and type/role must be strings; response-only fields in data (uid, password, creation_date, last_update, last_login) are ignored, so data made only of them is rejected. Use the block/allow list tools for sender-list changes.
  • proofpoint_essentials_users_delete ⚠ destructive, irreversible
  • proofpoint_essentials_users_block_list_add — add entries to a user's block list
  • proofpoint_essentials_users_block_list_remove — remove entries from a user's block list ⚠ high-impact
  • proofpoint_essentials_users_allow_list_add — add entries to a user's allow list ⚠ high-impact
  • proofpoint_essentials_users_allow_list_remove — remove entries from a user's allow list ⚠ high-impact

The create serialization and result normalization fix requires @wyre-ai/node-proofpoint-essentials >= 1.0.2. users_create / domains_create treat a returned User (primary_email) or Domain (name) with no error fields as succeeded even when Proofpoint omits status/success. The single-user users_get path fix needs @wyre-ai/node-proofpoint-essentials >= 1.1.1, which this package depends on.

Sender-list tools

There are 28 tools in total, including these eight. They have no list argument: block and allow are separate tools because the WYRE gateway grants access per tool name, not per argument. block_list_add is a routine, idempotent write meant for unattended automation. The other six are high-impact: allow-listing lets mail from that sender bypass spam filtering, removing a block entry re-admits a blocked sender, and removing an allow entry sends that sender's mail back through filtering.

ToolChangesTier
proofpoint_essentials_org_block_list_addorg block list, addroutine
proofpoint_essentials_org_block_list_removeorg block list, removehigh-impact
proofpoint_essentials_org_allow_list_addorg allow list, addhigh-impact
proofpoint_essentials_org_allow_list_removeorg allow list, removehigh-impact
proofpoint_essentials_users_block_list_adduser block list, addroutine
proofpoint_essentials_users_block_list_removeuser block list, removehigh-impact
proofpoint_essentials_users_allow_list_adduser allow list, addhigh-impact
proofpoint_essentials_users_allow_list_removeuser allow list, removehigh-impact

Parameters: orgDomain, email (users tools only), and entries, an array of 1 to 100 strings (each 1 to 320 characters). Entries are de-duplicated case-insensitively (first spelling wins) and matched case-insensitively.

How a change works: read the current lists, change only the target list, and write it with PATCH. The PATCH body holds only the target list, so the other list is never written. Then re-read and verify that both lists hold exactly the expected entries (compared case-insensitively as sets): the target list as modified, the other list as first read. An omitted list counts as empty in that comparison. If nothing would change, no write is made (changed: false). If verification fails, or the lists cannot be read as an object of string lists, the tool returns an error instead of a success. The mismatch error gives counts and one short sample per differing list, because error text is cut at 300 characters and email addresses in it are redacted. These operations are not atomic: read, change, write, re-read.

An invalid entry is reported by its position in your entries array (for example Invalid entry 51 of 61), since the entry text itself may be redacted in the error.

The result reports list, changed, verified (after a confirmed write), added / skipped_already_present or removed / skipped_not_present, counts of both lists, and the target list entries (or entries_omitted: true above 100 entries or when any entry is longer than 320 characters). Adding also reports also_on_allow_list or also_on_block_list for requested entries that are on the other list; the other list is never written.

Accepted entries:

  • email local@domain (local part 1 to 64 characters, * allowed, so *@example.com works)
  • domain with at least two labels (example.com), each label 1 to 63 ASCII letters, digits or hyphens, not starting or ending with a hyphen, host at most 253 characters, last label starting with a letter
  • IPv4 address (192.168.1.10), IPv4 wildcard only as a.b.c.* or a.b.*.* (10.91.*.*), or CIDR from /24 to /32 (192.168.1.0/24); numbers are written without leading zeros

Refused: whitespace, control characters, < > " ', IPv6, wildcards in a host (*.example.com, *.com, *@*.com; list the domain itself), *, and ranges larger than /24. The same rules apply to the remove tools, so an existing entry that breaks them (for example 10.0.0.0/8) cannot be removed with these tools; remove it in the Proofpoint console.

Known limit: there is no public-suffix list, so entries such as co.uk or gmail.com are accepted. Review entries before adding them.

Caveat: the sender-lists endpoints, their response keys and the PATCH semantics (merge or replace) come from the @wyre-ai/node-proofpoint-essentials SDK and have not been exercised against a live Proofpoint account. Treat the first live use with care. Known limits:

  • Whether PATCH merges or replaces is unverified. If PATCH replaced the whole resource, the other list would be cleared, and the re-read would show it and the call would report an unconfirmed write, provided the first read returned entries on that list. A populated other list that the upstream omits from its responses reads as empty, so its loss would not be seen.
  • A missing target key (including an empty response: an empty object, 204, or an empty body) reads as an empty list, so an add is written as just the new entries; if the upstream omits a populated target list, that list is overwritten. A removal from a missing target list is a no-op.
  • Concurrent changes to the same list are last-write-wins: both calls read, change and write the whole list, so the later write can undo the earlier one. If PATCH merges, a concurrent change to the other list is not overwritten, because only the target list is written. If it lands between this call's read and re-read, the call reports an unconfirmed write although its own change was applied; retrying is safe, because the retry finds nothing left to change.

There is no sender-list read tool yet. These tools require @wyre-ai/node-proofpoint-essentials >= 1.1.0.

Endpoint discovery

  • proofpoint_essentials_endpoint_discover — resolve which region hosts a customer domain

Features / Licensing / Package

  • proofpoint_essentials_features_get / proofpoint_essentials_features_update ⚠ high-impact
  • proofpoint_essentials_licensing_get / proofpoint_essentials_licensing_update ⚠ high-impact
  • proofpoint_essentials_package_update ⚠ high-impact

Reporting

  • proofpoint_essentials_reporting_get — inbound/outbound email flow metrics

Token

  • proofpoint_essentials_token_create — mint an Odin-based SSO token

Destructive tools require explicit confirmation. Interactive MCP clients are prompted via elicitation; non-interactive callers (e.g. the WYRE gateway) must pass confirm_destructive_action: true and are otherwise blocked.

Development

bash
git clone https://github.com/WYRE-AI/proofpoint-essentials-mcp.gitcd proofpoint-essentials-mcpnpm installnpm run buildnpm testnpm run smoke   # requires a prior `npm run build`

Contributing

Contributions are welcome! Please see CONTRIBUTING.md, or open an issue to discuss changes.

Error redaction

Error text and cleaned batch-result messages redact email addresses, including supported encoded @ forms (%40, %2540, &#64;, &#x40;, &commat;, literal \u0040, and full-width @), spaced @ forms, and quoted local parts. Domain-tool errors and cleaned domain-create messages also redact bare hostnames. Vendor error bodies are reduced to statusCode and scalar code metadata; other vendor fields are omitted. Each error text or cleaned per-item message is capped at 300 Unicode code points after redaction (the aggregate batch JSON is not capped). Confirmed all-success results retain raw data; this is targeted redaction, not general PII removal.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

來源:README.md,提交 1ace504

工具

0
SourceWeft 曾在隔離沙箱中以無憑證方式啟動該軟體包一次,以列出其工具,但未能完成:該軟體包類型無法在沙箱中執行。

版本歷史

7
  1. v1.1.1最新Nov 20, 2026
  2. v1.1.0Nov 16, 2026
  3. v1.0.4Nov 15, 2026
  4. v1.0.3Oct 24, 2026
  5. v1.0.2Oct 23, 2026
  6. v1.0.1Oct 14, 2026
  7. v1.0.0Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分