Skip to main content
Glama
proofpoint-essentials-mcp

proofpoint-essentials-mcp

by WYRE-AI

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

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

Related MCP server: Sophos Central MCP Server

Configuration

Copy .env.example and set the variables below.

Variable

Required

Description

PROOFPOINT_ESSENTIALS_USERNAME

For stdio and AUTH_MODE=env

Org-administrator username (sent as the X-User header)

PROOFPOINT_ESSENTIALS_PASSWORD

For stdio and AUTH_MODE=env

Org-administrator password (sent as the X-Password header)

PROOFPOINT_ESSENTIALS_REGION

No

Region subdomain, e.g. us1 or eu1 (default: us1)

MCP_TRANSPORT

No

stdio (default) or http

AUTH_MODE

No

gateway (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_SECRET

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 (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_DEV

No

Set 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_HOST

No

Bind 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_PORT

No

HTTP 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:

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-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.

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:

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:

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:

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.

Tool

Changes

Tier

proofpoint_essentials_org_block_list_add

org block list, add

routine

proofpoint_essentials_org_block_list_remove

org block list, remove

high-impact

proofpoint_essentials_org_allow_list_add

org allow list, add

high-impact

proofpoint_essentials_org_allow_list_remove

org allow list, remove

high-impact

proofpoint_essentials_users_block_list_add

user block list, add

routine

proofpoint_essentials_users_block_list_remove

user block list, remove

high-impact

proofpoint_essentials_users_allow_list_add

user allow list, add

high-impact

proofpoint_essentials_users_allow_list_remove

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.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

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, &#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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      13
      1
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      100
      52 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to manage WatchGuard Cloud MSP accounts, activate devices and licenses, and administer operator users through the WatchGuard Cloud REST API.
      13
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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