MCP Server

workonward-mcp exposes the PING8 Send API to Model Context Protocol clients. It is built on the Python workonward SDK and is safety-first by default: dry-run is on, an empty recipient allowlist denies every send, and limits are enforced server-side.

Use it when you want Claude Code, Claude Desktop, Claude.ai web connectors, Cursor, ChatGPT custom connectors, Windsurf, or Zed to validate, preview, and send email through PING8 with auditable controls.

Install

cd SDK/mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
workonward-mcp --check

Python 3.11+ is required. If a client cannot find the package with python -m workonward_mcp, use the absolute path to the virtualenv Python, such as /path/to/SDK/mcp/.venv/bin/python.

Tools

Tool	Side effect	Use first
`validate_recipients(recipients[])`	none	Check syntax and allowlist matches
`preview_send(recipient, attribs?, addresser?)`	none	Inspect the exact request before sending
`send_email(recipient, attribs?, addresser?, idempotency_key?)`	sends one email when dry-run is off	Preview the same recipient first
`send_batch_email(recipients[], attribs?, addresser?, idempotency_key?, confirm_token?)`	sends many emails when dry-run is off	Validate the full list first

Models can request tool calls, but the server enforces recipient allowlist checks, dry-run mode, batch-size caps, rate limits, idempotency, and audit logging.

Required Configuration

export WORKONWARD_API_KEY="YOUR_API_KEY"
export WORKONWARD_BASE_URL="https://mail.gitdate.ink"
export WORKONWARD_MCP_RECIPIENT_ALLOWLIST='@yourdomain\.com$'
export WORKONWARD_MCP_DRY_RUN=1

Keep WORKONWARD_MCP_DRY_RUN=1 until you have run validate_recipients and preview_send through your MCP client. To permit real sends, set WORKONWARD_MCP_DRY_RUN=0 only after the allowlist, audit path, and rate limits are confirmed.

Choose A Transport

Mode	Recommended clients	Notes
`stdio` + `env`	Claude Code, Claude Desktop, Cursor, Windsurf, Zed	The client starts a local process and passes secrets through environment variables
`http` + `bearer`	Internal services, CI, trusted private networks	Requires `Authorization: Bearer <token>` and TLS or explicit local-dev acknowledgement
`http` + `oauth`	Claude.ai web connectors, ChatGPT custom connectors	Requires a public HTTPS endpoint and OAuth 2.1 configuration

Use WORKONWARD_MCP_TRANSPORT and WORKONWARD_MCP_AUTH to switch modes. For public remote connectors, use https://mcp.gitdate.ink/mcp as the connector URL.

Client Setup Guides

Client	Recommended mode	Page
Claude Code	`stdio` + `env`	Claude Code
Claude Desktop	`stdio` + `env`	Claude Desktop
Claude.ai web connectors	`http` + `oauth`	Claude.ai Web
Cursor	`stdio` + `env`	Cursor
ChatGPT custom connectors	`http` + `oauth`	ChatGPT
Windsurf	`stdio` + `env`	Windsurf
Zed	`stdio` + `env`	Zed

Safe First Test

Start with WORKONWARD_MCP_DRY_RUN=1.
Set WORKONWARD_MCP_RECIPIENT_ALLOWLIST to a narrow regex, such as your internal test domain only.
Ask the model to call validate_recipients with one allowed and one blocked address.
Ask the model to call preview_send for one allowed recipient.
Inspect the preview, audit log, and client approval prompt.
Set WORKONWARD_MCP_DRY_RUN=0 only when you are ready for real sends.

Production Guardrails

Empty recipient allowlist means deny all sends.
Dry-run is on by default.
Batch size is capped by WORKONWARD_MCP_MAX_BATCH_SIZE.
Rate limits are enforced per auth subject.
Reused idempotency keys return cached results instead of sending again.
WORKONWARD_MCP_AUDIT_LOG_PATH writes JSONL audit records with recipient hashes, not raw recipient addresses.
API keys, bearer tokens, and OAuth signing keys are redacted in config output.

CLI

workonward-mcp
workonward-mcp --check
workonward-mcp --print-config
workonward-mcp --transport http
workonward-mcp --generate-signing-key

--print-config redacts secrets before printing.

Rust Claude Code