npm package: @getguru/sumologic-mcp
Description: SumoLogic MCP server for log searches, dashboards, monitors, and collectors
Latest version: 0.0.1

# SumoLogic MCP Server

MCP server for querying SumoLogic logs, dashboards, monitors, and collectors via the REST API.

## Features

- **Log Search**: Execute async search jobs with automatic polling and result retrieval
- **Slug Search**: Find logs containing card slugs or draft UUIDs (for Pylon telemetry correlation)
- **Dashboards**: List and get dashboard details
- **Monitors**: List monitors, get details, and check alert status
- **Collectors**: List collectors, get details, and view sources

## Installation

```bash
cd packages/sumologic-mcp
yarn install
yarn build
```

## Configuration

Set the following environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `SUMO_ACCESS_ID` | Yes | Access ID for API authentication |
| `SUMO_ACCESS_KEY` | Yes | Access Key for API authentication |
| `SUMO_API_BASE_URL` | Yes* | Full API base URL (e.g., `https://api.us2.sumologic.com/api`) |
| `SUMO_DEPLOYMENT` | Yes* | Region code (e.g., `us2`) - alternative to base URL |

*Either `SUMO_API_BASE_URL` or `SUMO_DEPLOYMENT` must be set.

### SumoLogic Deployment URLs

Find your deployment from your SumoLogic URL (e.g. `service.us2.sumologic.com` → `us2`):

| Deployment | API Base URL |
|------------|-------------|
| us1 | `https://api.sumologic.com/api` |
| us2 | `https://api.us2.sumologic.com/api` |
| eu | `https://api.eu.sumologic.com/api` |
| au | `https://api.au.sumologic.com/api` |
| ca | `https://api.ca.sumologic.com/api` |
| de | `https://api.de.sumologic.com/api` |
| jp | `https://api.jp.sumologic.com/api` |
| kr | `https://api.kr.sumologic.com/api` |
| fed | `https://api.fed.sumologic.com/api` |

### Getting API Credentials

1. Log in to SumoLogic
2. Go to **Administration > Security > Access Keys**
3. Click **Add Access Key**
4. Copy the Access ID and Access Key (shown once)
5. Add to your `.env` file

## Tools

### sumologic_search

Execute a SumoLogic log search query. Handles async job creation, polling, and result retrieval.

**Parameters:**
- `query` (required): SumoLogic search expression
  - Example: `_sourceCategory=prod/app error`
  - Example: `_sourceCategory=prod/api | count by _sourceHost`
- `time_range` (optional): Time range - `15m`, `1h`, `24h`, `7d`, or `today` (default: `1h`)
- `max_results` (optional): Maximum results to return (default: 100)

**Example:**
```json
{
  "query": "_sourceCategory=prod/app error | timeslice 5m | count",
  "time_range": "24h",
  "max_results": 50
}
```

### sumologic_search_by_slug

Search logs for a card slug or draft UUID (from Pylon). Useful for correlating Pylon issues to backend logs.

**Parameters:**
- `slug` (required): Card slug (e.g., `TLqRrKzc`) or draft UUID
- `source_category` (optional): Source category filter (default: `prod/*`)
- `days` (optional): Number of days to search back (default: 30)

**Example:**
```json
{
  "slug": "TLqRrKzc",
  "source_category": "prod/api",
  "days": 7
}
```

### sumologic_list_dashboards

List SumoLogic dashboards with pagination.

**Parameters:**
- `limit` (optional): Max results per page (default: 100)
- `token` (optional): Pagination token from previous response

### sumologic_get_dashboard

Get detailed information about a specific dashboard.

**Parameters:**
- `dashboard_id` (required): Dashboard ID (e.g., `00000000001A2B3C`)

### sumologic_list_monitors

List all SumoLogic monitors (alerts).

**Parameters:** None

### sumologic_get_monitor

Get detailed information about a specific monitor.

**Parameters:**
- `monitor_id` (required): Monitor ID (e.g., `00000000001A2B3C`)

### sumologic_get_monitor_status

Get the current alert status for a specific monitor.

**Parameters:**
- `monitor_id` (required): Monitor ID (e.g., `00000000001A2B3C`)

### sumologic_list_collectors

List SumoLogic collectors with optional filtering.

**Parameters:**
- `limit` (optional): Max results per page (default: 100)
- `offset` (optional): Pagination offset (default: 0)
- `filter` (optional): Filter by type/status - `installed`, `hosted`, `dead`, `alive`

### sumologic_get_collector

Get detailed information about a specific collector.

**Parameters:**
- `collector_id` (required): Collector ID (e.g., `12345`)

### sumologic_get_collector_sources

Get all sources configured for a specific collector.

**Parameters:**
- `collector_id` (required): Collector ID (e.g., `12345`)

## Usage with Claude Code

Add to your MCP settings (`.claude/mcp.json` or Claude Code settings):

```json
{
  "mcpServers": {
    "sumologic": {
      "command": "node",
      "args": ["/path/to/bug-triage-automator/packages/sumologic-mcp/dist/index.js"],
      "env": {
        "SUMO_ACCESS_ID": "your-access-id",
        "SUMO_ACCESS_KEY": "your-access-key",
        "SUMO_API_BASE_URL": "https://api.us2.sumologic.com/api"
      }
    }
  }
}
```

Or use environment variables from `.env` in the project root.

## Search Job Workflow

The `sumologic_search` tool handles the complete async search job workflow:

1. **Create Job**: POST to `/v1/search/jobs` with query and time range
2. **Poll Status**: Poll `/v1/search/jobs/{id}` every 2 seconds until `DONE GATHERING RESULTS`
3. **Fetch Results**: GET `/v1/search/jobs/{id}/messages` (raw logs) or `/records` (aggregations)
4. **Cleanup**: DELETE `/v1/search/jobs/{id}` to free up quota

The tool automatically:
- Handles cookie-based session affinity
- Determines whether to fetch messages or records based on query type
- Formats results as markdown tables
- Cleans up jobs even on errors

## Rate Limits

- 4 requests per second (240/minute) per user
- 10 concurrent requests per access key
- 200 concurrent active search jobs per organization
- 20 concurrent searches when querying Frequent Tier

## Error Handling

| Status | Meaning |
|--------|---------|
| 401 | Invalid credentials - check `SUMO_ACCESS_ID` and `SUMO_ACCESS_KEY` |
| 403 | Insufficient permissions - user role may lack required capabilities |
| 404 | Resource not found or search job timed out |
| 429 | Rate limited - automatic retry with backoff |

## References

- [SumoLogic REST API Documentation](https://help.sumologic.com/docs/api/)
- [Search Job API](https://help.sumologic.com/docs/api/search-job/)
- [Dashboard API](https://help.sumologic.com/docs/api/dashboard-management/)
- [Monitor API](https://help.sumologic.com/docs/api/monitors-management/)
- [Collector API](https://help.sumologic.com/docs/api/collector-management/)