Nevent AI troubleshooting

Error codes

All Nevent AI tools return structured errors with a machine-readable code field.

Code	Type	Meaning	Recovery
invalid_token	authentication_error	JWT missing, expired or malformed	Re-authenticate; verify NEVENT_JWT_TOKEN
forbidden	authentication_error	Insufficient role (ADMIN / SUPERADMIN required)	Use an account with the required role
not_found	not_found	Resource does not exist or belongs to another tenant	Verify the ID; check the active tenant
rate_limit_exceeded	rate_limit_error	Too many requests — param contains retry-after seconds	Wait and retry
server_error	api_error	Upstream API with 5xx — transient error	Retry with exponential backoff
network_error	api_error	Could not reach the upstream API (timeout or DNS)	Check connectivity; verify NEVENT_API_URL
segment_not_found	not_found	Segment ID not found in the active tenant	Verify the ID with nevent_list_segments
invalid_segment_definition	invalid_request	Segment DSL validation failed	Check criterion_ids against nevent_segmentation_criteria
missing_update_fields	invalid_request	Update call with no fields to modify	Provide at least name or definition
tenant_required	invalid_request	Tool requires an active tenant	Call nevent_switch_tenant first
operation_mode_blocked	invalid_request	Write tool called in READ_ONLY mode	Set NEVENT_OPERATION_MODE=STANDARD or FULL
feature_gate_not_enrolled	not_found	Tenant not enrolled in the provider insights pilot	Contact admin to activate MODULE_ATTRIBUTION

Error response 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)"
  }
}

Common problems

Claude does not detect Nevent tools

Symptom: Claude responds without mentioning Nevent tools or says it doesn’t have access to Nevent data.

Diagnosis:

1. Verify the MCP server is registered:

   claude mcp list  # for Claude Code

   For Claude Desktop, check that claude_desktop_config.json has the nevent block and that the JSON syntax is valid.

2. Check that the server process starts correctly:

   NEVENT_JWT_TOKEN=your_token node dist/index.js

   The server should start without errors. If there is a module not found error, run npm run build first.

3. Restart the client. Claude Desktop and Cursor load MCP servers at startup — a configuration change requires restarting the application.

401 Unauthorized error

Symptom: Tools return invalid_token.

Common causes:

• The JWT token has expired
• The NEVENT_JWT_TOKEN variable is not defined or has extra spaces
• The token belongs to a different environment (dev vs production)

Solution:

# Verify the token is defined
echo $NEVENT_JWT_TOKEN

# Get a fresh token
curl -X POST https://api.nevent.es/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "your_password"}' \
  | jq '.token'

Tenant switch failed

Symptom: nevent_switch_tenant returns an error or the active tenant does not change.

Common causes:

• The tenantId does not exist or is not accessible with the current user’s role
• The current JWT does not have the OWNER or SUPERADMIN permissions needed to access the destination tenant

Solution:

1. Call nevent_list_tenants to get the exact IDs of accessible tenants
2. Verify that the tenantId you pass to nevent_switch_tenant is in that list
3. Check the user’s role in the Nevent Admin console

Write tool returns operation_mode_blocked

Symptom: You try to create a campaign or segment and the server returns operation_mode_blocked.

Solution:

# In stdio mode
export NEVENT_OPERATION_MODE=STANDARD

# In claude_desktop_config.json
{
  "env": {
    "NEVENT_OPERATION_MODE": "STANDARD"
  }
}

feature_gate_not_enrolled in paid media insights

Symptom: The nevent_paid_attribution or nevent_get_paid_campaign_insights tools return feature_gate_not_enrolled.

Cause: The tenant is not enrolled in the MODULE_ATTRIBUTION module, which is in pilot phase.

Solution: Contact the Nevent team at support@nevent.ai to activate the attribution module on your account.

HTTP server not responding (self-hosted mode)

Symptom: The server starts but HTTP requests fail or OAuth doesn’t work.

Checks:

1. MCP_TRANSPORT=http is defined — without this, the server starts in stdio mode
2. MCP_JWT_SECRET has at least 32 characters
3. MONGODB_URI is accessible from the server
4. MCP_SERVER_URL points to the public HTTPS URL of the server (needed for the OAuth redirect)

# Basic endpoint test
curl https://your-server/health

Claude Desktop on macOS does not inherit environment variables

Symptom: The server starts but NEVENT_JWT_TOKEN is not defined.

Cause: On macOS, GUI apps do not inherit shell environment variables (.zshrc, .bashrc).

Solution: Include the token directly in claude_desktop_config.json:

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

Get in-session contextual help

The server includes a help tool that the agent can invoke when in doubt:

nevent_help({ topic: "errors" })
nevent_help({ topic: "workflows" })
nevent_help({ topic: "tenants" })
nevent_help({ topic: "analytics" })

These responses are tailored to the server context and current version.

Support

If the problem persists after reviewing this guide, write to support@nevent.ai with:

• Package version (mcp-nevent --version or the version from package.json)
• Transport mode (stdio or HTTP)
• The exact error code from the response
• Steps to reproduce the problem

Next step

• Tools reference
• Full environment variables
• Multi-tenant model