proofpoint-essentials-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
npm install @wyre-ai/proofpoint-essentials-mcpRelated MCP server: Sophos Central MCP Server
Configuration
Copy .env.example and set the variables below.
Variable | Required | Description |
| For stdio and | Org-administrator username (sent as the |
| For stdio and | Org-administrator password (sent as the |
| No | Region subdomain, e.g. |
| No |
|
| No |
|
| Yes for HTTP | Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder ( |
| No | Set to exactly |
| No | Bind address when |
| No | HTTP port. Defaults to |
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:
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.
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.
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": "org-admin@example.com",
"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:
{
"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)
claude mcp add proofpoint-essentials-mcp \
-e PROOFPOINT_ESSENTIALS_USERNAME=your-value \
-e PROOFPOINT_ESSENTIALS_PASSWORD=your-value \
-- npx -y @wyre-ai/proofpoint-essentials-mcpDocker
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.
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-mcpCompose 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:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses PROOFPOINT_ESSENTIALS_USERNAME and 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-mcpLocal 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:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm startAvailable 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.
Tool | Changes | Tier |
| org block list, add | routine |
| org block list, remove | high-impact |
| org allow list, add | high-impact |
| org allow list, remove | high-impact |
| user block list, add | routine |
| user block list, remove | high-impact |
| user allow list, add | high-impact |
| user allow list, remove | high-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.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 letterIPv4 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
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
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for Checkpoint Harmony Email & Collaboration (Avanan). Enables AI assistants to manage email security, anti-phishing, anti-malware, and threat detection via the Avanan API.131Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI-powered security operations through natural language, managing endpoint security, email threats, firewall policy, and more across multiple Sophos tenants with 334 tools, designed for MSP/MSSP teams.10052 npm1MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to manage WatchGuard Cloud MSP accounts, activate devices and licenses, and administer operator users through the WatchGuard Cloud REST API.13Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MSPs and security teams to manage customer tenants, licenses and usage billing, and to run security operations such as searching events and secured emails, maintaining allow/block exception rules, and quarantining or restoring messages. It is exposed as a stateless, multi-tenant Streamable HTTP endpoint that takes credentials per request via headers.Apache 2.0