Proofpoint Essentials

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

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": "[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:

{
  "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).

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

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
• proofpoint_essentials_users_delete ⚠ destructive, irreversible

The create serialization and result normalization fix requires @wyre-ai/node-proofpoint-essentials >= 1.0.2, which this package depends on.

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