WebEngage MCP 服务器

🚀 WebEngage MCP Server

Connect any AI assistant to the WebEngage platform through the Model Context Protocol

Track users · Log events · Trigger campaigns — all through natural language

Built with ❤️ by Shivam Tiwari

📖 Table of Contents

• Overview
• What is MCP?
• Features
• Architecture
• Prerequisites
• Installation
• Configuration
• Usage
  • Claude Desktop
  • Cursor IDE
  • MCP Inspector
• Available Tools
  • webengage_track_user
  • webengage_track_event
  • webengage_trigger_campaign
  • webengage_bulk_track_users
  • webengage_bulk_track_events
• Available Resources
• Project Structure
• Rate Limits
• Error Handling
• Development
• Troubleshooting
• Contributing
• License

🌟 Overview

webengage-mcp is a Model Context Protocol (MCP) server that acts as a bridge between AI assistants and the WebEngage customer engagement platform. It exposes WebEngage's REST API as structured MCP tools, allowing AI models to:

• Create and update user profiles with system and custom attributes
• Track custom events with rich metadata for analytics and segmentation
• Trigger transactional campaigns across push, SMS, email, WhatsApp, and web push
• Perform bulk operations for high-throughput data ingestion

Instead of writing API calls manually, simply tell your AI assistant what you need in plain English.

🤖 What is MCP?

The Model Context Protocol (MCP) is an open standard created by Anthropic that provides a universal way for AI models to interact with external tools and data sources. Think of it as a "USB-C port for AI" — one standardised interface that connects any AI client to any service.

┌─────────────────┐     MCP (JSON-RPC)     ┌──────────────────┐     REST API     ┌──────────────┐
│   AI Assistant   │◄──────────────────────►│  webengage-mcp   │◄───────────────►│   WebEngage   │
│ (Claude, Cursor) │       over stdio       │   MCP Server     │    over HTTPS   │   Platform    │
└─────────────────┘                         └──────────────────┘                 └──────────────┘

Key MCP concepts used in this server:

✨ Features

🛠️ 5 MCP Tools

📚 2 MCP Resources

🔒 Security

• API keys are never exposed to the AI model — only a masked version is available via the credentials resource
• Bearer token authentication on all API calls
• Input validation via Zod schemas with descriptive error messages

🌍 Multi-Region Support

🏗️ Architecture

webengage-mcp/
│
├── src/index.ts          ← MCP Server bootstrap (stdio transport)
│       │
│       ├── Registers 5 Tools ─────────────────────────────────────────────┐
│       │   ├── track_user.ts        → POST /v1/accounts/{LC}/users       │
│       │   ├── track_event.ts       → POST /v1/accounts/{LC}/events      │
│       │   ├── trigger_campaign.ts  → POST /v1/accounts/{LC}/transactions│
│       │   ├── bulk_track_users.ts  → POST /v1/accounts/{LC}/users/bulk  │
│       │   └── bulk_track_events.ts → POST /v1/accounts/{LC}/events/bulk │
│       │                                                                  │
│       ├── Registers 2 Resources ─────────────────────────────────────────┤
│       │   ├── credentials.ts       → webengage://credentials            │
│       │   └── api_reference.ts     → webengage://api-reference          │
│       │                                                                  │
│       └── Uses ──────────────────────────────────────────────────────────┤
│           ├── config.ts            → Env variable loading & validation  │
│           └── client.ts            → Typed HTTP client (fetch-based)    │
│                                                                          │
└───────────────────────── All calls → WebEngage REST API ─────────────────┘

📋 Prerequisites

• Node.js ≥ 18 (uses native fetch)
• npm ≥ 9
• A WebEngage account with REST API access enabled
• Your API Key and License Code from the WebEngage dashboard

Finding Your WebEngage Credentials

1. Log in to your WebEngage Dashboard
2. Navigate to Data Platform → Integrations → REST API
3. Copy your API Key and License Code

📦 Installation

# Clone the repository
git clone https://github.com/shivamtiwari3/webengage-mcp.git
cd webengage-mcp

# Install dependencies
npm install

# Build the TypeScript source
npm run build

⚙️ Configuration

The server is configured entirely through environment variables:

The server constructs the base URL automatically:

https://api.{dc}.webengage.com/v1/accounts/{LICENSE_CODE}

🔌 Usage

1. Claude Desktop

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "webengage": {
      "command": "node",
      "args": ["/absolute/path/to/webengage-mcp/dist/index.js"],
      "env": {
        "WEBENGAGE_API_KEY": "your_api_key_here",
        "WEBENGAGE_LICENSE_CODE": "your_license_code_here",
        "WEBENGAGE_DC": "in"
      }
    }
  }
}

Restart Claude Desktop. You should see a 🔌 icon indicating the MCP server is connected.

Example prompts you can now use:

2. Cursor IDE

Add to your Cursor MCP settings (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "webengage": {
      "command": "node",
      "args": ["/absolute/path/to/webengage-mcp/dist/index.js"],
      "env": {
        "WEBENGAGE_API_KEY": "your_api_key_here",
        "WEBENGAGE_LICENSE_CODE": "your_license_code_here",
        "WEBENGAGE_DC": "in"
      }
    }
  }
}

3. MCP Inspector (Debugging)

The MCP Inspector provides a visual UI to test all tools and resources:

npx @modelcontextprotocol/inspector tsx src/index.ts

Open http://localhost:5173 in your browser to interact with the server directly.

🔧 Available Tools

1. webengage_track_user

Purpose: Create or update a user profile in WebEngage.

Parameters:

Example request:

{
  "userId": "user_001",
  "email": "shivam@example.com",
  "firstName": "Shivam",
  "lastName": "Tiwari",
  "phone": "+919876543210",
  "attributes": {
    "plan": "premium",
    "signup_source": "organic"
  }
}

Example response:

{
  "success": true,
  "message": "User \"user_001\" tracked successfully",
  "response": { "status": "queued" }
}

2. webengage_track_event

Purpose: Track a custom user event for analytics, segmentation, and campaign triggers.

Parameters:

Example request:

{
  "userId": "user_001",
  "eventName": "Product Purchased",
  "attributes": {
    "product_name": "Wireless Earbuds",
    "price": 2499,
    "currency": "INR",
    "category": "Electronics"
  }
}

⚠️ Important: Event names must not start with we_ — that prefix is reserved for WebEngage system events.

3. webengage_trigger_campaign

Purpose: Trigger a transactional campaign for a specific user. The campaign must already be in "Running" state on the WebEngage dashboard.

Parameters:

Example request:

{
  "campaignId": "camp_order_confirm",
  "userId": "user_001",
  "channel": "email",
  "tokens": {
    "order_id": "ORD-12345",
    "delivery_date": "2026-02-25",
    "total_amount": "₹2,499"
  }
}

💡 Tip: Unlike marketing campaigns, transactional campaigns use personalisation tokens passed through the API instead of user attributes.

4. webengage_bulk_track_users

Purpose: Batch-upsert up to 100 user profiles in a single API call.

Parameters:

Each user object supports: userId (required), email, phone, firstName, lastName, attributes.

Example request:

{
  "users": [
    { "userId": "u1", "email": "a@test.com", "firstName": "Alice" },
    { "userId": "u2", "email": "b@test.com", "firstName": "Bob" },
    { "userId": "u3", "email": "c@test.com", "firstName": "Charlie" }
  ]
}

5. webengage_bulk_track_events

Purpose: Batch-track up to 100 events in a single API call.

Parameters:

Each event object supports: userId (required), eventName (required), eventTime, attributes.

Example request:

{
  "events": [
    { "userId": "u1", "eventName": "Page Viewed", "attributes": { "page": "/pricing" } },
    { "userId": "u2", "eventName": "Button Clicked", "attributes": { "button": "signup" } }
  ]
}

📚 Available Resources

webengage://credentials

Returns a masked view of your current connection configuration. Useful for the AI to verify which account it's connected to without exposing sensitive keys.

Example output:

# WebEngage Connection Info

- **License Code:** ~12a3b4c
- **Data Center:** in
- **API Key:** we_a****xyz9
- **Base URL:** https://api.in.webengage.com/v1/accounts/~12a3b4c

webengage://api-reference

Returns a compact markdown reference of all WebEngage REST API endpoints, rate limits, and data constraints. This gives the AI model the context it needs to autonomously decide which tool to use for a given request.

⚡ Rate Limits

WebEngage enforces rate limits on its REST API. This server does not implement client-side rate limiting — requests are passed through to WebEngage directly.

🚨 Error Handling

All tools return structured JSON responses. On failure, you'll get:

{
  "error": "WebEngage API error [401] POST /users: {\"message\":\"Invalid API key\"}"
}

Common error scenarios:

💻 Development

# Run in development mode (auto-restarts on changes)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector tsx src/index.ts

Tech Stack

🔍 Troubleshooting

Server won't start

• Ensure WEBENGAGE_API_KEY and WEBENGAGE_LICENSE_CODE are set
• Verify Node.js ≥ 18: node --version
• Run npm run build first if using npm start

Tools not appearing in Claude Desktop

• Verify the config file path is correct for your OS
• Ensure the args path in config is an absolute path to dist/index.js
• Restart Claude Desktop completely after config changes
• Check Claude Desktop logs for MCP errors

API calls returning 401

• Regenerate your API key from WebEngage Dashboard → Data Platform → Integrations → REST API
• Ensure you're using the correct data center (global, in, or sa)

Campaign trigger returning 400

• The campaign must be in "Running" state on the WebEngage dashboard
• Verify the campaignId is correct
• Ensure the channel matches the campaign type

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit: git commit -m 'Add amazing feature'
5. Push: git push origin feature/amazing-feature
6. Open a Pull Request

Ideas for Future Tools

• 📊 webengage_get_segment — Fetch user segment data
• 📈 webengage_campaign_stats — Get campaign performance metrics
• 🔔 webengage_create_campaign — Create campaigns programmatically
• 🗑️ webengage_delete_user — GDPR-compliant user deletion

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ by Shivam Tiwari
_{Powered by Model Context Protocol · WebEngage}