SumoLogic MCP Server by greyaperez - MCP Server

SumoLogic MCP Server

Transform SumoLogic interactions with natural language - A Model Context Protocol (MCP) server that makes SumoLogic operations as simple as asking questions in plain English.

🚀 What Makes This Special

This isn't just another API wrapper. With contextual awareness powered by sumologic-context.json, you can interact with SumoLogic using natural language that understands your specific environment, resources, and common queries.

Before vs After

Before (Traditional API):

# Complex API calls with exact syntax
curl -X POST "https://api.sumologic.com/api/v1/search/jobs" \
  -H "Authorization: Basic <encoded>" \
  -d '{"query":"_sourceCategory=webapp | count by _sourceHost", "from":"2024-01-01T00:00:00", "to":"2024-01-01T23:59:59"}'

After (Natural Language with Context):

"Show me error counts from our production web servers yesterday"
"Which collectors are having ingestion issues?"
"Create a dashboard for our new microservice deployment"

🎯 Key Features

🧠 Contextual Intelligence

The sumologic-context.json configuration transforms basic API access into an intelligent assistant that knows:

Your specific collectors and their purposes
Common queries and their business meaning
Resource relationships and dependencies
Team-specific terminology and workflows

🔧 Complete SumoLogic Operations

Connection Management: Verify connectivity and health
Collectors & Sources: Create, manage, and monitor data ingestion
Search & Analytics: Execute complex queries with natural language
Monitors & Alerts: Manage monitoring configurations
Dashboards: Create and update visualizations

💬 Natural Language Interface

Ask questions like:

"What's the error rate for our payment service this week?"
"Show me slow database queries from the last hour"
"Create a collector for our new Kubernetes cluster"
"Are there any critical alerts I should know about?"

🌟 The Power of sumologic-context.json

What is Contextual Awareness?

The sumologic-context.json file is your secret weapon. It teaches the MCP server about your specific SumoLogic environment, enabling incredibly intuitive interactions.

Real-World Context Configuration

{
  "version": "1.0",
  "organization": "acme-corp",
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "sourceName": "nginx-*",
          "description": "Production web frontend servers (Nginx)",
          "commonFilters": ["_sourceHost=web-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400",
            "_sourceCategory=\"prod/web/frontend\" | timeslice 1m | count by status_code",
            "_sourceCategory=\"prod/web/frontend\" | json field=response_time | avg(response_time)"
          ]
        },
        "api-backend": {
          "sourceCategory": "prod/api/backend", 
          "sourceName": "api-server-*",
          "description": "Production API backend services",
          "commonFilters": ["_sourceHost=api-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/api/backend\" error OR exception",
            "_sourceCategory=\"prod/api/backend\" | json field=response_time | avg(response_time) by endpoint",
            "_sourceCategory=\"prod/api/backend\" | where status_code = 500"
          ]
        },
        "mobile-app": {
          "sourceCategory": "prod/mobile/app",
          "sourceName": "mobile-api-*",
          "description": "Production mobile application backend",
          "commonFilters": ["_sourceHost=mobile-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/mobile/app\" crash OR exception",
            "_sourceCategory=\"prod/mobile/app\" | json field=user_id | count by user_id"
          ]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql",
          "sourceName": "postgres-*",
          "description": "Production PostgreSQL database logs",
          "commonFilters": ["_sourceHost=db-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/database/postgresql\" slow query",
            "_sourceCategory=\"prod/database/postgresql\" | where duration > 1000"
          ]
        },
        "kubernetes": {
          "sourceCategory": "prod/k8s/containers",
          "sourceName": "k8s-*",
          "description": "Production Kubernetes cluster logs",
          "commonFilters": ["_sourceHost=k8s-*"],
          "namespaces": ["default", "production", "monitoring", "ingress-nginx"]
        }
      }
    },
    "staging": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "staging/web/frontend",
          "sourceName": "nginx-staging-*",
          "description": "Staging web frontend servers"
        },
        "api-backend": {
          "sourceCategory": "staging/api/backend", 
          "sourceName": "api-staging-*",
          "description": "Staging API backend services"
        }
      }
    }
  },
  "shortcuts": {
    "errors": {
      "description": "Find error messages and exceptions",
      "queryTemplate": "error OR exception OR fatal OR \"stack trace\" OR \"internal server error\"",
      "timeRange": "-15m"
    },
    "performance": {
      "description": "Performance monitoring with configurable threshold",
      "queryTemplate": "response_time OR duration OR latency | where ${metric} > ${threshold}",
      "defaultParams": {
        "metric": "response_time", 
        "threshold": "1000"
      },
      "timeRange": "-1h"
    },
    "security": {
      "description": "Security-related events and authentication failures",
      "queryTemplate": "authentication OR authorization OR \"access denied\" OR \"unauthorized\"",
      "timeRange": "-1h"
    },
    "database-slow": {
      "description": "Slow database queries",
      "queryTemplate": "\"slow query\" OR (duration > ${threshold}) OR \"query timeout\"",
      "defaultParams": {
        "threshold": "5000"
      },
      "timeRange": "-30m"
    }
  },
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost",
    "service_field": "service_name",
    "environment_field": "environment",
    "log_level_field": "level"
  }
}

Contextual Examples in Action

With this sophisticated context configuration, see how natural and powerful these interactions become:

Example 1: Multi-Environment Error Analysis

You ask: "Compare error rates between production and staging web frontend"

AI intelligently:

Identifies web-frontend in both production and staging environments
Uses context-aware queries:
- Production: _sourceCategory="prod/web/frontend" | where status_code >= 400
- Staging: _sourceCategory="staging/web/frontend" | where status_code >= 400
Applies appropriate time ranges and provides comparative analysis
Reports: "Production web frontend: 0.2% error rate (normal), Staging: 1.1% error rate (elevated - likely from recent deployment testing)"

Example 2: Infrastructure Health Check

You ask: "How is our Kubernetes cluster performing?"

AI automatically:

Maps "Kubernetes cluster" to prod/k8s/containers source category
Checks across configured namespaces: default, production, monitoring, ingress-nginx
Applies infrastructure-specific filters: _sourceHost=k8s-*
Uses sample queries for container health and resource usage
Responds: "K8s cluster healthy: 247 running pods across 4 namespaces. No resource constraints detected in production namespace."

Example 3: Smart Shortcut Usage

You ask: "Show me slow database queries from the last hour"

AI leverages shortcuts:

Recognizes "slow database queries" maps to database-slow shortcut
Applies the template: "slow query" OR (duration > 5000) OR "query timeout"
Targets PostgreSQL logs: _sourceCategory="prod/database/postgresql"
Uses default threshold (5000ms) and custom time range (-1h)
Results: "Found 12 slow queries in the last hour. Average duration: 7.2s. Most frequent: user authentication queries."

Example 4: Cross-Service Performance Analysis

You ask: "What's causing the mobile app performance issues?"

AI performs comprehensive analysis:

Identifies mobile-app application context
Runs mobile-specific queries: _sourceCategory="prod/mobile/app" crash OR exception
Cross-references with api-backend performance: avg(response_time) by endpoint
Checks database logs for related slow queries
Synthesizes findings: "Mobile app shows 15% increase in crash rate. Root cause: API endpoint /user/profile averaging 3.2s response time due to database connection pool exhaustion."

Example 5: Security Incident Response

You ask: "Check for any security issues in the last hour"

AI uses security shortcut:

Applies security shortcut template across all production applications
Searches: authentication OR authorization OR "access denied" OR "unauthorized"
Scans web-frontend, api-backend, and mobile-app simultaneously
Correlates findings across services
Reports: "Security alert: 47 unauthorized access attempts detected on API backend from IP 192.168.1.100. Web frontend shows corresponding 403 responses."

📋 Prerequisites

Node.js 20+ (LTS recommended)
SumoLogic account with API access
API credentials (Access ID and Key)
Docker (optional, for containerized deployment)

⚡ Quick Start

1. Installation

git clone https://github.com/greyaperez/mcp-sumologic.git
cd mcp-sumologic
npm install

2. Configuration

# Copy environment template
cp .env.example .env

Edit .env with your SumoLogic credentials:

SUMOLOGIC_ACCESS_ID=your_access_id
SUMOLOGIC_ACCESS_KEY=your_access_key
SUMOLOGIC_API_ENDPOINT=https://api.us2.sumologic.com/api
SUMOLOGIC_CONTEXT_CONFIG=./sumologic-context.json

3. Create Your Context File

Create sumologic-context.json with your environment details:

{
  "version": "1.0",
  "organization": "your-org",
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "sourceName": "nginx-*",
          "description": "Production web frontend servers",
          "commonFilters": ["_sourceHost=web-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400"
          ]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql",
          "sourceName": "postgres-*", 
          "description": "Production PostgreSQL database logs",
          "commonFilters": ["_sourceHost=db-prod-*"]
        }
      }
    }
  },
  "shortcuts": {
    "errors": {
      "description": "Find error messages and exceptions",
      "queryTemplate": "error OR exception OR fatal",
      "timeRange": "-15m"
    }
  },
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost",
    "service_field": "service_name"
  }
}

4. Run the Server

# Development mode
npm run dev

# Production mode
npm run build && npm start

🐳 Docker Deployment

Build and Run

# Build image
docker build -t mcp/sumologic .

# Run with environment variables
docker run -i --rm \
  -e SUMOLOGIC_ACCESS_ID="your_access_id" \
  -e SUMOLOGIC_ACCESS_KEY="your_access_key" \
  -e SUMOLOGIC_API_ENDPOINT="https://api.us2.sumologic.com/api" \
  -e SUMOLOGIC_CONTEXT_CONFIG="./sumologic-context.json" \
  mcp/sumologic

🔧 Claude Desktop Integration

Add to your Claude Desktop configuration:

Option 1: Direct Node.js

{
  "mcpServers": {
    "sumologic": {
      "command": "node",
      "args": ["/path/to/mcp-sumologic/dist/index.js"],
      "env": {
        "SUMOLOGIC_ACCESS_ID": "your_access_id",
        "SUMOLOGIC_ACCESS_KEY": "your_access_key",
        "SUMOLOGIC_API_ENDPOINT": "https://api.us2.sumologic.com/api",
        "SUMOLOGIC_CONTEXT_CONFIG": "./sumologic-context.json"
      }
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "sumologic": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SUMOLOGIC_ACCESS_ID",
        "-e", "SUMOLOGIC_ACCESS_KEY", 
        "-e", "SUMOLOGIC_API_ENDPOINT",
        "-e", "SUMOLOGIC_CONTEXT_CONFIG",
        "mcp/sumologic"
      ],
      "env": {
        "SUMOLOGIC_ACCESS_ID": "your_access_id",
        "SUMOLOGIC_ACCESS_KEY": "your_access_key",
        "SUMOLOGIC_API_ENDPOINT": "https://api.us2.sumologic.com/api",
        "SUMOLOGIC_CONTEXT_CONFIG": "./sumologic-context.json"
      }
    }
  }
}

🛠️ Available Tools

Tool	Description	Context-Aware
`check_connection`	Verify API connectivity	✅
`list_collectors`	List all collectors with business context	✅
`get_collector`	Get collector details with relationship info	✅
`create_hosted_collector`	Create collector with smart defaults	✅
`update_collector`	Update collector properties	✅
`delete_collector`	Delete collector with impact analysis	✅
`list_sources`	List sources with purpose descriptions	✅
`get_source`	Get source details with context	✅
`create_http_source`	Create HTTP source with templates	✅
`start_search_job`	Execute searches with query suggestions	✅
`check_search_job_status`	Check search status	✅
`get_search_job_results`	Get results with business interpretation	✅
`list_monitors`	List monitors with business impact	✅
`get_monitor`	Get monitor details with context	✅

💡 Best Practices for Context Configuration

1. Organize by Environment and Service Type

{
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "description": "Production web frontend servers (Nginx)",
          "commonFilters": ["_sourceHost=web-prod-*"]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql", 
          "description": "Production PostgreSQL database logs"
        }
      }
    }
  }
}

2. Include Real SumoLogic Queries

{
  "sampleQueries": [
    "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400",
    "_sourceCategory=\"prod/api/backend\" | json field=response_time | avg(response_time) by endpoint"
  ]
}

3. Create Reusable Query Shortcuts

{
  "shortcuts": {
    "performance": {
      "description": "Performance monitoring with configurable threshold",
      "queryTemplate": "response_time OR duration OR latency | where ${metric} > ${threshold}",
      "defaultParams": {
        "metric": "response_time", 
        "threshold": "1000"
      },
      "timeRange": "-1h"
    }
  }
}

4. Standardize Field Mappings

{
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost", 
    "service_field": "service_name",
    "environment_field": "environment",
    "log_level_field": "level"
  }
}

5. Use Consistent Naming Patterns

Source Categories: {env}/{service-type}/{service-name}
Source Names: {service}-{env}-* (e.g., nginx-prod-*)
Host Filters: _sourceHost={service}-{env}-*

🔍 Usage Examples

Environment-Aware Queries

"Show me errors in production web frontend"
"Compare API performance between staging and production"  
"Check database health in all environments"

Shortcut-Powered Analysis

"Run security check for the last hour"
"Find slow database queries with default threshold"
"Show performance issues with response time over 2000ms"

Infrastructure Intelligence

"How is our Kubernetes cluster doing?"
"Check Redis cache hit rates in production"
"Show load balancer health across all environments"

Cross-Service Correlation

"Is the mobile app backend causing the database slowdown?"
"Compare error rates between web frontend and API backend"
"Show the full request flow from load balancer to database"

Proactive Management

"Create a monitor for API response times over 1 second"
"Set up alerting for Kubernetes pod crashes"
"Monitor database connection pool exhaustion"

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

Ready to transform your SumoLogic experience? Start with a simple context file and watch as complex operations become as easy as asking questions! 🚀