http streaming mcp transport with embedded api key authentication
Enables direct HTTPS/SSE connection from modern MCP clients (Claude Desktop 0.48.0+, VS Code Copilot, OpenAI Responses API) to the Wassenger MCP server at https://api.wassenger.com/mcp without local installation. API key is embedded as URL query parameter and validated on every request, eliminating OAuth complexity for stateless clients. Uses Server-Sent Events (SSE) for bidirectional message streaming over standard HTTPS.
Unique: Implements stateless HTTP streaming transport with query-parameter API key validation, eliminating the need for local OAuth flows or proxy servers for modern MCP clients. Uses standard HTTPS/SSE rather than custom protocols, enabling deployment on any CDN or reverse proxy.
vs alternatives: Faster onboarding than NPX package setup (no Node.js installation) and more secure than embedding credentials in client config files, though less suitable for sensitive environments than OAuth-based alternatives.
npx package stdio-to-sse proxy with oauth 2.0 + pkce authentication
Provides a local Node.js proxy (mcp-wassenger NPX package) that bridges STDIO transport from legacy MCP clients (Cline, Continue) to SSE connection with the Wassenger API. Implements OAuth 2.0 with PKCE flow for secure credential handling, using lockfile-based coordination (src/lib/coordination.ts) to prevent duplicate browser authentication flows when multiple client instances spawn the proxy simultaneously. Parses command-line arguments and manages credential lifecycle.
Unique: Implements lockfile-based multi-instance coordination (src/lib/coordination.ts 12-143) to prevent duplicate OAuth browser flows when multiple client processes spawn the proxy concurrently. Uses PKCE (Proof Key for Code Exchange) for secure OAuth without client secrets in memory, and bridges STDIO ↔ SSE bidirectionally via MCP SDK transports.
vs alternatives: More secure than HTTP streaming's query-parameter API keys (uses OAuth tokens with expiration) and supports legacy clients, but requires local installation and adds startup latency vs direct HTTP streaming.
mcp tool schema generation and validation with type safety
Automatically generates MCP tool schemas (JSON Schema format) for all Wassenger API operations, with built-in type validation and parameter documentation. Implements schema validation on tool invocation to catch missing or invalid parameters before sending to Wassenger API. Provides TypeScript type definitions for all tool inputs/outputs, enabling IDE autocomplete and compile-time type checking.
Unique: Generates MCP tool schemas with embedded TypeScript type definitions, enabling compile-time type checking and IDE autocomplete for Wassenger operations. Implements client-side parameter validation to catch errors before API calls.
vs alternatives: More developer-friendly than raw JSON schemas (TypeScript types + autocomplete) and more reliable than runtime-only validation, though less flexible than dynamic schema generation from live API introspection.
error handling and retry logic with exponential backoff
Implements comprehensive error handling for Wassenger API failures, including network errors, rate limiting (HTTP 429), and API errors (HTTP 4xx/5xx). Provides automatic retry logic with exponential backoff (initial delay 100ms, max delay 30s) for transient failures, with configurable retry counts. Returns detailed error messages to AI clients, distinguishing between retryable errors (rate limit, timeout) and permanent failures (invalid parameters, authentication).
Unique: Implements exponential backoff retry logic with configurable retry counts and distinguishes between retryable errors (rate limit, timeout) and permanent failures (invalid parameters). Provides detailed error metadata to clients for intelligent error handling.
vs alternatives: More resilient than single-attempt API calls and more transparent than silent retries (returns detailed error info), though less sophisticated than circuit breaker patterns for cascading failure prevention.
configuration management with environment variable and file-based secrets
Provides flexible configuration loading from environment variables, command-line arguments, and configuration files (.env, JSON). Implements secure credential storage with support for API keys, OAuth secrets, and webhook URLs. Validates configuration on startup and provides helpful error messages for missing or invalid settings. Supports configuration inheritance and overrides (CLI args > env vars > config files).
Unique: Implements configuration loading with priority order (CLI args > env vars > config files) and validates all settings on startup, providing helpful error messages for missing or invalid configurations. Supports both .env files and JSON configuration files.
vs alternatives: More flexible than hardcoded configuration and more accessible than external secret management services (Vault, AWS Secrets Manager), though less secure than encrypted secret storage and requires manual credential rotation.
whatsapp message sending with recipient validation and delivery tracking
Enables AI clients to send text messages to WhatsApp contacts or groups via the Wassenger API, with built-in recipient validation (phone number format checking, contact existence verification) and delivery status tracking. Implements message queuing to handle rate limits (typically 80 messages/minute per Wassenger account) and provides structured responses indicating success, pending, or failure states. Supports both individual chats and group messaging with automatic recipient type detection.
Unique: Integrates recipient validation and delivery status tracking directly into the MCP tool interface, allowing AI clients to handle failures and retries without external polling. Implements client-side rate limit awareness to prevent API quota exhaustion during batch operations.
vs alternatives: More integrated than raw Wassenger API calls (validation + status tracking built-in) and more reliable than webhook-based delivery tracking (synchronous responses), though less feature-rich than Twilio's WhatsApp API for complex media handling.
conversation history retrieval and context extraction
Provides AI clients with the ability to fetch and analyze WhatsApp conversation history from specific chats or groups, extracting message content, sender metadata, timestamps, and media references. Implements pagination for large conversations (typically 50-100 messages per page) and optional filtering by date range or sender. Returns structured conversation data suitable for RAG (Retrieval-Augmented Generation) pipelines or conversation analysis tasks.
Unique: Exposes conversation history as structured MCP tools with built-in pagination and filtering, enabling AI clients to fetch context on-demand without managing separate API calls or database queries. Integrates directly with LLM context windows for immediate use in prompts.
vs alternatives: More accessible than raw Wassenger API (pagination + filtering built-in) and more real-time than webhook-based conversation logging, though less feature-rich than dedicated conversation analytics platforms like Intercom for advanced segmentation.
group and team management with member administration
Enables AI clients to create WhatsApp groups, add/remove members, update group metadata (name, description, icon), and manage group permissions. Implements role-based access control (admin vs member) and provides group listing with member counts and metadata. Supports bulk member operations with error handling for invalid phone numbers or permission violations.
Unique: Provides group management as atomic MCP tools with built-in error handling for permission violations and invalid members, allowing AI clients to orchestrate group operations without managing WhatsApp API complexity. Supports bulk member operations with partial success reporting.
vs alternatives: More integrated than raw Wassenger API (error handling + bulk operations built-in) and more accessible than WhatsApp Business API direct integration (no webhook management required), though less feature-rich than dedicated group management platforms for advanced analytics.
+5 more capabilities