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:

1. Identifies web-frontend in both production and staging environments
2. Uses context-aware queries:
   • Production: _sourceCategory="prod/web/frontend" | where status_code >= 400
   • Staging: _sourceCategory="staging/web/frontend" | where status_code >= 400
3. Applies appropriate time ranges and provides comparative analysis
4. 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:

1. Maps "Kubernetes cluster" to prod/k8s/containers source category
2. Checks across configured namespaces: default, production, monitoring, ingress-nginx
3. Applies infrastructure-specific filters: _sourceHost=k8s-*
4. Uses sample queries for container health and resource usage
5. 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:

1. Recognizes "slow database queries" maps to database-slow shortcut
2. Applies the template: "slow query" OR (duration > 5000) OR "query timeout"
3. Targets PostgreSQL logs: _sourceCategory="prod/database/postgresql"
4. Uses default threshold (5000ms) and custom time range (-1h)
5. 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:

1. Identifies mobile-app application context
2. Runs mobile-specific queries: _sourceCategory="prod/mobile/app" crash OR exception
3. Cross-references with api-backend performance: avg(response_time) by endpoint
4. Checks database logs for related slow queries
5. 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:

1. Applies security shortcut template across all production applications
2. Searches: authentication OR authorization OR "access denied" OR "unauthorized"
3. Scans web-frontend, api-backend, and mobile-app simultaneously
4. Correlates findings across services
5. 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
SUMOLOGIC_DEFAULT_TIMEZONE=UTC

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" \
  -e SUMOLOGIC_DEFAULT_TIMEZONE="UTC" \
  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",
        "SUMOLOGIC_DEFAULT_TIMEZONE": "UTC"
      }
    }
  }
}

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",
        "-e", "SUMOLOGIC_DEFAULT_TIMEZONE",
        "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",
        "SUMOLOGIC_DEFAULT_TIMEZONE": "UTC"
      }
    }
  }
}

🛠️ 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

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

📄 License

This project is licensed under the MIT License - see the LICENSE 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! 🚀