Coralogix MCP Server

MCP server exposing a Coralogix query tool for AI agents.

Overview

This Model Context Protocol (MCP) server provides tools for AI agents to query Coralogix logs and manage alert definitions using either Lucene or DataPrime syntax.

Installation

Install the MCP server using npm:

npx -y @nickholden/coralogix-mcp-server@latest

MCP Configuration

Add this configuration to your MCP settings file (e.g., cline_mcp_settings.json):

"coralogix-mcp-server": {
  "autoApprove": [
    "coralogix_query",
    "create_alert",
    "update_alert",
    "delete_alert",
    "get_alert",
    "list_alerts"
  ],
  "disabled": false,
  "timeout": 60,
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@nickholden/coralogix-mcp-server@latest"
  ],
  "env": {
    "CORALOGIX_API_KEY": "PUT_YOUR_API_KEY_HERE",
    "CORALOGIX_REGION": "auto",
    "CORALOGIX_ENV": "production"
  }
}

Getting a Coralogix API Key

1. Log in to your Coralogix account
2. Navigate to Settings → API Keys
3. Create a new API key with appropriate permissions (see Required Permissions below)
4. Copy the key and replace PUT_YOUR_API_KEY_HERE in the configuration above

Required Permissions

The MCP server requires specific permissions based on the operations you want to perform:

Essential Permissions (Required for all operations):

• Logs Query - Required for coralogix_query tool
• External API Access - Required for all alert management operations

Alert Management Permissions:

• Alerts Management - Required for create_alert, list_alerts, get_alert operations
• Integrations Read - Required for notification groups functionality (converts integration names to IDs)

API Key Type:

• Personal API Key recommended - Works with all v2 External API endpoints
• Team-scoped API keys may have limitations with certain endpoints

Operations by Permission Level:

| Operation | Required Permissions | API Endpoint Used | |-----------|---------------------|-------------------| | coralogix_query | Logs Query | /api/v1/dataprime/query | | create_alert | Alerts Management + Integrations Read | /api/v2/external/alerts + /api/v1/external/integrations | | list_alerts | Alerts Management | /api/v2/external/alerts | | get_alert | Alerts Management | /api/v2/external/alerts (via list) | | update_alert | Alerts Management + Integrations Read | /com.coralogixapis.alerts.v3.AlertDefsService/ReplaceAlertDef (gRPC-Web) | | delete_alert | Alerts Management | /com.coralogixapis.alerts.v3.AlertDefsService/DeleteAlertDef (gRPC-Web) |

Note about Notification Groups: The server automatically converts friendly integration names to the required numeric IDs:

1. With Integrations Permission: Uses /api/v1/external/integrations endpoint for real-time lookup
2. Without Integrations Permission: Falls back to known integration mappings:
   • "attorneys-stats-errors" → ID: 7047 (Slack)
   • "vinny-dispatch-alerts" → ID: 8447 (Slack)
   • "required-documents-alerts" → ID: 10426 (Slack)

Recommendation: Add "Integrations Read" permission to your API key for full integration discovery. The fallback ensures core functionality works even without this permission.

Regional Configuration

The server automatically detects your Coralogix region, but you can configure it explicitly:

Environment Variables:

• CORALOGIX_REGION: Set to eu, us1, us2, ap1, ap2, or auto (default: auto-detect)
• CORALOGIX_ENV: Optional - Set to production, staging, or development for debugging context
• NODE_ENV: Alternative to CORALOGIX_ENV for environment identification

Supported Regions:

• eu: Europe (coralogix.com)
• us1: US East (us1.coralogix.com)
• us2: US West (us2.coralogix.com)
• ap1: Asia Pacific India (app.coralogix.in)
• ap2: Asia Pacific Singapore (coralogixsg.com)

If region auto-detection fails, check your API key and network connectivity.

Environment Configuration Examples

Production Environment:

{
  "env": {
    "CORALOGIX_API_KEY": "your_production_api_key",
    "CORALOGIX_REGION": "eu",
    "CORALOGIX_ENV": "production"
  }
}

Staging Environment:

{
  "env": {
    "CORALOGIX_API_KEY": "your_staging_api_key", 
    "CORALOGIX_REGION": "eu",
    "CORALOGIX_ENV": "staging"
  }
}

Development Environment:

{
  "env": {
    "CORALOGIX_API_KEY": "your_dev_api_key",
    "CORALOGIX_REGION": "eu", 
    "CORALOGIX_ENV": "development"
  }
}

Development Setup

For local development:

git clone https://github.com/nickohold/coralogix-mcp-server.git
cd coralogix-mcp-server
npm install
npm run build

Usage

Available Tools

The server exposes the following tools:

coralogix_query

Query Coralogix logs and aggregations.

Parameters:

• query (string, required): Lucene/DataPrime query string
• syntax (string, optional): "QUERY_SYNTAX_LUCENE" or "QUERY_SYNTAX_DATAPRIME" (default)
• startDate (string, optional): ISO-8601 start date (default: now - 15 min)
• endDate (string, optional): ISO-8601 end date (default: now)
• limit (integer, optional): Maximum results (1-1000)

Alert Management Tools

create_alert: Create a new alert definition

• alert (object, required): Alert definition with name, description, priority, etc.
• alert.notificationGroups (array, optional): List of integration names for notifications (e.g., ["slack-alerts"])

update_alert: Update an existing alert

• id (string, required): Alert ID
• alert (object, required): Updated alert properties
• Supports notification groups with automatic integration ID lookup

delete_alert: Delete an alert

• id (string, required): Alert ID
• safety (object, optional): Safety configuration (deprecated but kept for compatibility)

get_alert: Get a specific alert by ID

• id (string, required): Alert ID

list_alerts: List all alerts with optional filtering

• limit (number, optional): Maximum alerts to return
• offset (number, optional): Pagination offset
• filter (object, optional): Filter by enabled, priority, or alertType

Example Usage with AI Agent

Query recent error logs:

{
  "tool": "coralogix_query",
  "arguments": {
    "query": "source logs | filter severity == `Error`",
    "syntax": "QUERY_SYNTAX_DATAPRIME",
    "limit": 50
  }
}

Search for specific text in logs:

{
  "tool": "coralogix_query",
  "arguments": {
    "query": "error OR failed",
    "syntax": "QUERY_SYNTAX_LUCENE",
    "startDate": "2025-06-11T12:00:00.000Z",
    "endDate": "2025-06-11T13:00:00.000Z"
  }
}

Count logs by application:

{
  "tool": "coralogix_query",
  "arguments": {
    "query": "source logs | count by applicationName"
  }
}

Create an alert with Slack notifications:

{
  "tool": "create_alert",
  "arguments": {
    "alert": {
      "name": "High Error Rate Alert",
      "description": "Alert when error rate exceeds threshold",
      "priority": "warning",
      "enabled": true,
      "alertType": "LOGS_THRESHOLD",
      "notificationGroups": ["slack-alerts", "team-notifications"],
      "filters": {
        "query": "level:ERROR",
        "severities": ["error"]
      },
      "conditions": {
        "threshold": 10,
        "timeWindow": "5MIN"
      }
    }
  }
}

Alert Management Features

Full alert lifecycle management using v2 External API:

Supported Operations

• create_alert: Create new alerts with notification groups
• update_alert: Update existing alerts (PUT operation)
• delete_alert: Delete alerts (DELETE operation)
• list_alerts: List and filter alerts
• get_alert: Get specific alert details

Key Features

• Notification Groups: Automatic conversion of integration names to IDs (requires integrations permission)
• Hybrid API Strategy: v2 for create/read, v3 for update/delete operations
• Full CRUD Support: Complete alert lifecycle management
• Error Handling: Comprehensive error messages and context
• Regional Support: Automatic region detection

Development

Setup

git clone <repository>
cd coralogix-mcp-server
npm install

Build

npm run build

Watch Mode

npm run watch

Testing

npm test

Inspector

Use the MCP inspector to test the server:

npm run inspector

API Reference

Alert Management Endpoints

The server uses Coralogix External API v2 for optimal compatibility:

• CREATE: External API v2 (/api/v2/external/alerts) with notification group support
• READ (GET/LIST): External API v2 (/api/v2/external/alerts)
• UPDATE: gRPC-Web v3 (/com.coralogixapis.alerts.v3.AlertDefsService/ReplaceAlertDef)
• DELETE: gRPC-Web v3 (/com.coralogixapis.alerts.v3.AlertDefsService/DeleteAlertDef)

API Version Strategy:

• v2 External API: Primary API for create and read operations (simple, reliable)
• v3 gRPC-Web API: Used for update and delete operations (full functionality)
• v1 External API: Used only for integration lookup (/api/v1/external/integrations) and DataPrime queries (/api/v1/dataprime/query)

This hybrid approach provides full CRUD functionality while using the most appropriate API version for each operation.

Notification Groups

The server automatically converts notification group names (e.g., "slack-alerts") to the required numeric integration IDs using the /api/v1/external/integrations endpoint. This enables seamless Slack and webhook notifications without manual ID lookup.

API Documentation

For detailed API schemas and protobuf definitions, refer to the official Coralogix documentation:

• v3 gRPC API Schema: GitHub - coralogix/cx-api-alerts
• Official API Documentation: Coralogix Alerts API v3

Note: The GitHub repository contains the authoritative protobuf definitions and examples for the v3 gRPC API.

Coralogix Query Syntax

The server supports both Lucene and DataPrime query syntaxes:

Lucene Examples:

• error OR failed - Search for logs containing "error" or "failed"
• severity:Error - Filter by severity level
• applicationName:"my-app" AND level:ERROR - Complex filtering

DataPrime Examples:

• source logs | filter severity == 'Error' - Filter error logs
• source logs | count by applicationName - Count by application
• source logs | filter timestamp > now() - 1h - Recent logs

Default Behavior

• Time Range: If no startDate/endDate provided, queries the last 15 minutes
• Syntax: Defaults to QUERY_SYNTAX_DATAPRIME if not specified
• Timeout: Requests timeout after 30 seconds

Error Handling

The server provides detailed error messages for:

• Missing or invalid API key
• Invalid query parameters
• Coralogix API errors
• Network timeouts

License

MIT