Nevent MCP Server

Nevent MCP

Talk to your live-events CRM (campaigns, analytics, paid ads, segments) in Claude and ChatGPT.

---

Install

Hosted (recommended — no install needed)

Add https://mcp.nevent.ai/mcp as a remote MCP server in your client (Claude.ai, ChatGPT, Cursor, Cline, Continue).

Local (stdio via npm)

npx mcp-nevent

Or install globally:

npm install -g mcp-nevent
mcp-nevent

Required env: NEVENT_JWT_TOKEN. Optional: NEVENT_OPERATION_MODE (READ_ONLY | STANDARD | FULL).

---

Quick add

Claude.ai (recommended — hosted, no setup)

1. Open Claude.ai → Settings → Integrations
2. Add custom connector → URL: https://mcp.nevent.ai/mcp
3. Authorize with your Nevent admin account

Claude Desktop / Cursor / Cline / Continue (stdio, local)

Build first if needed: npm install && npm run build

Add to your MCP client config:

{
  "mcpServers": {
    "nevent": {
      "command": "node",
      "args": ["/path/to/mcp-nevent/dist/index.js"],
      "env": {
        "NEVENT_JWT_TOKEN": "your_nevent_jwt_token"
      }
    }
  }
}

For Claude Desktop, the config file is:

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

For Claude Code:

claude mcp add nevent -- node /path/to/mcp-nevent/dist/index.js
export NEVENT_JWT_TOKEN=your_token

ChatGPT (custom connectors)

Settings → Connectors → Add custom MCP → URL https://mcp.nevent.ai/mcp. The OAuth flow will prompt you to log in with your Nevent admin account.

---

What you can ask

"Show me registrations for EventX broken down by ticket type"

"Which campaigns sent last month had an open rate above 30%?"

"Create a segment of all attendees who bought a VIP ticket in 2025
 but haven't opened any email in the last 90 days"

"Schedule the 'Summer Gala' email campaign for next Monday at 10:00 CET"

"Compare ROAS across our Meta ad campaigns for March"

"How many suppressions did we accumulate this month and what are the top reasons?"

"Create per-user tracking links for the Summer Gala campaign and show me which users clicked"

---

Tools (52)

Analytics & Segmentation

Multi-tenant + Segment Management

Campaigns

Templates

Deliverability

Paid Media (11 tools)

Short URLs (9 tools)

Track campaign link clicks, generate per-user tracking variants, and measure CTR across marketing campaigns.

---

How it works

LLM (Claude / ChatGPT)
        |
        | MCP over Streamable HTTP or stdio
        v
  ┌─────────────────┐
  │  Nevent MCP     │  mcp.nevent.ai (hosted) or local
  └─────────────────┘
        |
        | REST + JWT
        v
  Nevent APIs (analytics, campaigns, segments, paid media)

OAuth 2.1 is used for hosted (HTTP) mode: the MCP server acts as an authorization server, issuing short-lived JWT tokens after validating your Nevent credentials. Each session is isolated — no shared service accounts.

Privacy: tenant data is isolated per session. Data does not leave the Nevent infrastructure and is not used for model training.

---

For developers

Run locally (stdio)

npm install
npm run build
export NEVENT_JWT_TOKEN=your_token
node dist/index.js

Run locally (HTTP)

npm install
npm run build
MCP_JWT_SECRET=dev-secret-at-least-32-chars \
MONGODB_URI=mongodb://localhost:27017/mcp-nevent \
MCP_TRANSPORT=http \
node dist/index.js

Configuration

stdio mode:

HTTP mode:

Architecture brief

src/
├── index.ts                        # Entry point — stdio vs HTTP transport selection
├── server.ts                       # MCP server factory (transport-agnostic)
├── server-instructions.ts          # Server-level LLM instructions (session init)
├── auth/
│   ├── oauth-provider.ts           # OAuth 2.1 provider (login, token exchange)
│   ├── oauth-stores.ts             # MongoDB-backed OAuth stores
│   ├── token-service.ts            # JWT sign/verify with MCP_JWT_SECRET
│   └── login-page.ts               # HTML login page renderer
├── clients/
│   ├── base-client.ts              # Shared HTTP client (JWT auth, 401 auto-refresh)
│   ├── data-client.ts              # Data API client with TTL caches
│   ├── paid-media-client.ts        # Paid media endpoints client
│   ├── template-client.ts          # Template operation endpoints
│   └── session-clients.ts          # Per-session aggregate with atomic JWT rotation
├── config/
│   ├── operation-mode.ts           # READ_ONLY | STANDARD | FULL operation guard
│   └── timeouts.ts                 # Centralised timeout constants
├── tools/                          # One file per tool category
├── schemas/                        # Zod validation schemas per category
└── types/                          # TypeScript types per domain

Key design decisions:

• SessionClients provides atomic JWT rotation — if a tenant switch or 401 refresh fails mid-flight, neither the data client nor the paid media client is updated.
• TTL caches (5 min) in DataClient for capabilities and segmentation criteria reduce API calls on repeated tool invocations within a session.
• Operation mode guard (READ_ONLY / STANDARD / FULL) controls which write tools are available, protecting against accidental mutations.

See CONTRIBUTING.md for the development workflow.

---

Multi-tenant support

Nevent uses a hierarchical tenant model.

1. nevent_list_tenants      → list accessible tenants (returns tenant IDs)
2. nevent_switch_tenant     → set active tenant for this session
3. nevent_reset_tenant      → restore home tenant (SUPERADMIN)

Tenant switching contract

When you call nevent_switch_tenant:

1. The MCP server calls the tenant-switch endpoint on the Nevent API with { tenantId }.
2. The API validates that the JWT holder has access to the target tenant and returns a new access token scoped to the new tenant.
3. The MCP server updates the JWT in both DataClient (for analytics) and PaidMediaClient (for paid media) atomically.
4. All in-memory caches (capabilities, segmentation criteria) are invalidated — subsequent calls will fetch fresh data for the new tenant context.
5. activeTenantId is updated from the new JWT's tenantId claim.

When you call nevent_reset_tenant:

1. The MCP server reads homeTenantId — the tenant ID captured from the original JWT at session creation time.
2. It calls the tenant-switch endpoint with { tenantId: homeTenantId } to restore the original context.
3. Same cache invalidation and JWT rotation as nevent_switch_tenant.
4. If homeTenantId is not available (e.g. the original JWT had no tenantId claim), the tool returns an error.

Invariants:

• Tenant context is session-scoped — switching in one session does not affect any other user.
• The JWT rotation is atomic — if the API call fails, neither client is updated.
• The tool response includes the new active_tenant_id so the agent can verify the switch succeeded.

---

Common workflows

Analytics: querying event data

1. nevent_analytics_capabilities      → discover available tables
2. nevent_analytics_table_schema      → get exact column names for your table
3. nevent_analytics_filter_values     → get valid values for filter fields
4. nevent_analytics_query             → run the query

Segmentation: build and preview an audience

1. nevent_segmentation_criteria       → list available criterion_ids and operators
2. nevent_dimension_values            → autocomplete criterion values (e.g. event IDs)
3. nevent_segment_preview             → validate audience size before saving
4. nevent_create_segment              → persist the segment

Campaign: create and schedule a send

1. nevent_get_sending_profile         → verify sender domain is validated
2. nevent_get_suppressions_summary    → check suppression rate (warn if > 2%)
3. nevent_list_segments               → pick target audience (get segment_id)
4. nevent_segment_preview             → confirm audience count with user
5. nevent_list_templates              → pick email template (get template_id)
6. nevent_get_template                → inspect template content before sending
7. nevent_create_campaign             → create DRAFT (no messages sent yet)
8. nevent_schedule_campaign           → schedule delivery (confirmed=true required)

Performance analysis: how did a campaign perform?

1. nevent_list_campaigns              → find the campaign (filter by date/status)
2. nevent_get_campaign                → get full metrics (opens, clicks, bounces)
3. nevent_get_campaign_insights       → AI recommendations and anomaly detection
4. nevent_campaign_report             → deep analytics with 13 parallel queries

---

Error codes glossary

All tool errors return a machine-readable code field for programmatic handling.

Error format

All errors follow a structured format:

{
  "error": {
    "type": "authentication_error | invalid_request | api_error | rate_limit_error | not_found",
    "message": "Human-readable explanation with actionable guidance",
    "code": "machine_readable_code",
    "param": "offending_parameter (when applicable)"
  }
}

---

Roadmap

• Additional template operations (AI analysis, bulk import)
• Advanced audience builder (nested logic groups, multi-event sequences)
• Webhook tool support

---

Links

• Landing: https://nevent.ai/en/features/nevent-ai/
• Docs (coming soon): https://docs.nevent.ai/mcp
• Support: support@nevent.ai
• License: MIT
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md