Claude Code

Claude Code can run workonward-mcp as a local stdio server. This is the recommended mode for development because the server stays on your machine and receives the PING8 API key through environment variables.

Reference: Claude Code MCP documentation (opens in a new tab).

Install Locally

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

Keep the virtualenv active while adding the server, or use the absolute path to .venv/bin/python in the command.

Add The Server

export WORKONWARD_API_KEY="YOUR_API_KEY"
 
claude mcp add --transport stdio \
  --env WORKONWARD_API_KEY="$WORKONWARD_API_KEY" \
  --env WORKONWARD_BASE_URL=https://mail.gitdate.ink \
  --env "WORKONWARD_MCP_RECIPIENT_ALLOWLIST=@gitdate\\.ink$|@actualintelligence\\.ink$" \
  --env WORKONWARD_MCP_DRY_RUN=1 \
  --env WORKONWARD_MCP_AUDIT_LOG_PATH=/tmp/workonward-mcp-audit.jsonl \
  workonward -- python -m workonward_mcp

If Claude Code reports that the module cannot be found, replace python with the absolute virtualenv path:

/path/to/SDK/mcp/.venv/bin/python -m workonward_mcp

Claude Code options such as --transport, --env, and --scope must be placed before the server name. The command after -- is what Claude Code starts as the MCP server.

Verify

claude mcp list
claude mcp get workonward

Inside Claude Code, run:

/mcp

Then ask:

Use the workonward validate_recipients tool on ["person@gitdate.ink", "not-an-email"].

Expected result:

• The configured server appears as workonward.
• The tools list includes validate_recipients, preview_send, send_email, and send_batch_email.
• The invalid address is rejected before any send attempt.

Safe Send Workflow

Use this sequence in a Claude Code conversation:

Use workonward validate_recipients for this list first. Do not send yet.

Use workonward preview_send for user@gitdate.ink with attribs {"name":"Ada"}. Do not send yet.

If the preview recipient and body match exactly, use workonward send_email with idempotency_key "manual-smoke-001".

Keep WORKONWARD_MCP_DRY_RUN=1 until you intentionally want the send_* tools to hit the PING8 Send API.

Troubleshooting