Zignal MCP Server

MCP server for Zignal - AI agent analytics and signal detection.

This server allows AI assistants like Claude to track conversations, detect signals (user frustration, task failures, feature requests, etc.), and retrieve analytics in real-time.

Features

• Create Events: Track AI conversations and interactions
• List Events: Search and filter tracked events
• List Signals: Retrieve detected signals (issues, risks, feedback)

Installation

cd mcp-server-zignal
npm install
npm run build

Configuration

1. Get your Zignal API key

Sign up at zignal.dev and create a project to get your API key.

2. Configure Claude Desktop

Add the server to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "zignal": {
      "command": "node",
      "args": [
        "/absolute/path/to/zignal/mcp-server-zignal/dist/index.js"
      ],
      "env": {
        "ZIGNAL_API_KEY": "zk_proj_your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

The Zignal tools will now be available in Claude Desktop.

Environment Variables

• ZIGNAL_API_KEY (required): Your Zignal API key
• ZIGNAL_BASE_URL (optional): API base URL (defaults to https://kanshi-production.up.railway.app)

Available Tools

zignal_create_events

Create one or more events for AI signal classification.

Example:

{
  "events": [
    {
      "user_id": "user_123",
      "event": "ai.conversation",
      "properties": {
        "session_id": "sess_xyz"
      },
      "ai_data": {
        "model": "claude-3",
        "convo_id": "conv_abc",
        "input": "I can't figure out how to export my data",
        "output": "I'll help you export your data..."
      }
    }
  ]
}

zignal_list_events

List and search events with filters.

Parameters:

• limit: Number of events (1-100, default 50)
• cursor: Pagination cursor
• user_id: Filter by user
• convo_id: Filter by conversation
• event: Filter by event type
• has_signals: Filter events with/without signals
• signal_type: Filter by signal type (issue, risk, feedback)

zignal_list_signals

List detected signals across events.

Parameters:

• limit: Number of signals (1-1000, default 100)
• type: Filter by type (issue, risk, feedback, or all)
• name: Filter by signal name (partial match)

Signal Types

Events with ai_data.input and ai_data.output are automatically analyzed for:

| Signal | Type | Description | |--------|------|-------------| | User Frustration | issue | User expresses anger or dissatisfaction | | Task Failure | issue | AI failed to complete the request | | Escalation Needed | risk | Requires human intervention | | Confusion | issue | User doesn't understand the response | | Feature Request | feedback | User requests new capability | | Positive Feedback | feedback | User expresses satisfaction | | Bug Report | issue | User reports unexpected behavior |

Example Usage in Claude

Once configured, you can ask Claude:

"Track this conversation in Zignal and check for any signals"

"Show me the last 10 events where signals were detected"

"List all user frustration signals from today"

Claude will use the Zignal MCP server to track conversations and retrieve analytics automatically.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT