
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.
概覽
面向 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,閘道模式則要求每次請求附上憑證標頭。終端使用者帳號無法通過驗證。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Proofpoint Essentials,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
Proofpoint Essentials MCP Server
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
Configuration
Copy .env.example and set the variables below.
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:
<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.
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.
Usage
Running with Claude Desktop
Add to your Claude Desktop claude_desktop_config.json:
Running with Claude Code (CLI)
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.
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:
Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses PROOFPOINT_ESSENTIALS_USERNAME and PROOFPOINT_ESSENTIALS_PASSWORD:
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:
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 domainsproofpoint_essentials_org_set_active— activate/deactivate an org ⚠ high-impactproofpoint_essentials_org_delete— delete an org ⚠ destructive, irreversibleproofpoint_essentials_org_block_list_add— add entries to the org block listproofpoint_essentials_org_block_list_remove— remove entries from the org block list ⚠ high-impactproofpoint_essentials_org_allow_list_add— add entries to the org allow list ⚠ high-impactproofpoint_essentials_org_allow_list_remove— remove entries from the org allow list ⚠ high-impact
Domains
proofpoint_essentials_domains_listproofpoint_essentials_domains_create— params:orgDomain, non-emptydomains: 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 setsisError. Any failure or unconfirmed item makesresultsa 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-impactproofpoint_essentials_domains_delete⚠ destructive, irreversible
Users
proofpoint_essentials_users_listproofpoint_essentials_users_getproofpoint_essentials_users_create— params:orgDomain, non-emptyusers[]with requiredprimary_emailand optionalfirstname,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 setsisError. Any failure or unconfirmed item makesresultsa 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 byprimary_email) and merges on every update, also whentypeis 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).datamust not be empty andtype/rolemust be strings; response-only fields indata(uid, password, creation_date, last_update, last_login) are ignored, sodatamade only of them is rejected. Use the block/allow list tools for sender-list changes.proofpoint_essentials_users_delete⚠ destructive, irreversibleproofpoint_essentials_users_block_list_add— add entries to a user's block listproofpoint_essentials_users_block_list_remove— remove entries from a user's block list ⚠ high-impactproofpoint_essentials_users_allow_list_add— add entries to a user's allow list ⚠ high-impactproofpoint_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.
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.comworks) - 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 asa.b.c.*ora.b.*.*(10.91.*.*), or CIDR from/24to/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-impactproofpoint_essentials_licensing_get/proofpoint_essentials_licensing_update⚠ high-impactproofpoint_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
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, @, @, @, 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版本歷史
7- v1.1.1最新Nov 20, 2026
- v1.1.0Nov 16, 2026
- v1.0.4Nov 15, 2026
- v1.0.3Oct 24, 2026
- v1.0.2Oct 23, 2026
- v1.0.1Oct 14, 2026
- v1.0.0Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分