Skip to main content
Glama
spamtitan-mcp

spamtitan-mcp

by WYRE-AI

SpamTitan MCP Server

License Node.js

A Model Context Protocol (MCP) server for SpamTitan email security. Enables AI assistants to manage quarantine, maintain allowlists and blocklists, and view email filtering statistics.

This is a Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible AI) to your SpamTitan environment.

Part of the MSP Claude Plugins ecosystem — a growing suite of AI integrations for the MSP stack. Built by MSPs, for MSPs.

Installation

npm install @wyre-ai/spamtitan-mcp

Related MCP server: knowbe4-mcp

Configuration

Copy .env.example and set the variables below.

Variable

Required

Description

SPAMTITAN_API_KEY

For stdio and AUTH_MODE=env

SpamTitan API key

SPAMTITAN_BASE_URL

No

SpamTitan instance URL, including any path prefix (e.g. https://mail.example.com/spamtitan/). Defaults to https://api-spamtitan.titanhq.com. In gateway mode the per-request X-SpamTitan-Base-URL header takes precedence.

MCP_TRANSPORT

No

stdio (default) or http

AUTH_MODE

No

gateway (Docker image and Compose) or env. Gateway mode requires X-SpamTitan-API-Key on each /mcp request and does not fall back to SPAMTITAN_API_KEY. env uses that variable only after S2S auth succeeds. Unset means env (stdio and single-tenant HTTP).

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, replace-me, your-s2s-secret, replace-with-a-real-secret, and the other example values). Generate one with openssl rand -hex 32. Compose will not start without it. The value is never logged.

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, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST refuses to start. A known placeholder secret still refuses to start.

MCP_HTTP_HOST

No

Bind address when a real CONDUIT_S2S_SECRET is set. Unset keeps 0.0.0.0, the historical container bind. The image and Compose set 0.0.0.0 inside the container.

MCP_HTTP_PORT

No

HTTP port. Defaults to 8080.

/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. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-SpamTitan-API-Key: $SPAMTITAN_API_KEY" \
  -H "X-SpamTitan-Base-URL: $SPAMTITAN_BASE_URL" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In AUTH_MODE=gateway, /mcp also requires X-SpamTitan-API-Key. That header is the only API-key source for the request. X-SpamTitan-Base-URL is optional and, when present, selects the tenant instance. AUTH_MODE=env still requires the signed X-Gateway-S2S header, then uses SPAMTITAN_API_KEY and SPAMTITAN_BASE_URL from the environment.

Usage

Running with Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "spamtitan-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/spamtitan-mcp"],
      "env": {
        "SPAMTITAN_API_KEY": "your-spamtitan-api-key"
      }
    }
  }
}

Running with Claude Code (CLI)

claude mcp add spamtitan-mcp \
  -e SPAMTITAN_API_KEY=your-value \
  -- npx -y @wyre-ai/spamtitan-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 a real S2S secret. In gateway mode, SpamTitan credentials arrive on each request as headers; the API key is not read from the environment.

docker build -t spamtitan-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  spamtitan-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset or empty. The gateway service sets AUTH_MODE=gateway, does not inject SPAMTITAN_API_KEY or SPAMTITAN_BASE_URL, and publishes 127.0.0.1:8080:8080:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses SPAMTITAN_API_KEY and SPAMTITAN_BASE_URL. It is separate from the gateway Compose service above.

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SPAMTITAN_API_KEY=your-value \
  -e SPAMTITAN_BASE_URL=https://mail.example.com/spamtitan/ \
  -p 127.0.0.1:8080:8080 \
  spamtitan-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 (including the image default 0.0.0.0) makes startup exit:

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm start

Available Domains

Lists

Manage allowlists and blocklists

Quarantine

Email quarantine review and management

Stats

Email filtering statistics and reports

Features

  • Interactive quarantined-message card (MCP Apps, SEP-1865) — spamtitan_get_message renders as a read-only interactive card in MCP Apps hosts (Claude Desktop/web); plain-JSON behavior is unchanged in other hosts. The card is neutral by default, brandable via window.__BRAND__ injection or MCP_BRAND_* env vars (MCP_BRAND_NAME, MCP_BRAND_LOGO_URL, MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR, MCP_BRAND_BG, MCP_BRAND_TEXT) — no rebuild needed. Rebuild the card bundle with npm run build:ui after editing ui/.

Development

# Clone the repository
git clone https://github.com/WYRE-AI/spamtitan-mcp.git
cd spamtitan-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
MCP_TRANSPORT=http CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm start

# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm start

Contributing

Contributions are welcome! Please see CONTRIBUTING.md if present, or open an issue to discuss changes.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Available Tools

9 tools
spamtitan_delete_messageA
Destructive

⚠ DESTRUCTIVE — IRREVERSIBLE. Permanently delete a quarantined message by ID. This action cannot be undone and will remove the message from quarantine storage. Confirm with the user before invoking.

Inputs: message_id (required).

spamtitan_get_messageA

Get a single quarantined message by ID. Returns sender, recipient, subject, quarantine reason, spam score, and status. Renders as an interactive card in MCP Apps hosts.

Inputs: message_id (required).

spamtitan_get_queueA

List the email quarantine queue. Returns quarantined messages with sender, recipient, subject, and reason for quarantine.

Inputs: page, reason, sender, subject, +2 more.

spamtitan_get_statsA

Get email flow statistics from SpamTitan including messages received, blocked, quarantined, and delivered. Supports filtering by time period.

Inputs: domain, period.

spamtitan_manage_allowlistA

Add or remove sender allowlist entries in SpamTitan. Allowlisted senders always bypass spam filtering.

Inputs: action (required), note, sender.

spamtitan_manage_blocklistA
DestructiveIdempotent

⚠ HIGH-IMPACT. Add or remove sender blocklist entries in SpamTitan. Modifies email delivery policy and affects deliverability for users. Blocklisted senders are always rejected or quarantined. Reversible by removing entries. Confirm with the user before invoking.

Inputs: action (required), note, sender.

spamtitan_navigateA

Discover available SpamTitan tools by domain. Returns tool names and descriptions for the selected domain. All tools are callable at any time — this is a help/discovery aid, not a prerequisite.

Inputs: domain (required).

spamtitan_release_messageB

Release a quarantined message by ID, delivering it to the intended recipient.

Inputs: message_id (required).

spamtitan_statusB

Show credentials status and available domains

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource/action: status, discovery, queue listing, message retrieval, release, delete, allowlist management, blocklist management, and stats. The destructive and high-impact tools are clearly separated from safe read operations.

    Naming Consistency4/5

    The spamtitan_ prefix creates a consistent namespace, and most tools follow verb_noun naming (get_queue, get_message, release_message, delete_message, manage_allowlist, get_stats). spamtitan_status and spamtitan_navigate are minor deviations from that pattern.

    Tool Count5/5

    Nine tools is well-scoped for a SpamTitan server: quarantine lifecycle, list management, status, stats, and a discovery helper. Each tool earns its place without redundancy or bloat.

    Completeness4/5

    The quarantine workflow is fully covered with list, get, release, and delete, and allow/block list modifications plus stats are present. Minor gaps include no direct way to view current allowlist/blocklist entries and no search/filter for the queue, but these are workable.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    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
      Not graded
      quality
      B
      maintenance
      MCP server for ThreatLocker — zero-trust application allowlisting, approval requests, audit logs
      1
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      MCP server for Proofpoint Email Protection - email security, threat intelligence, TAP (Targeted Attack Protection), and email filtering API integration
      40
      6
      Apache 2.0