sumo-mcp-readonly

A read-only Model Context Protocol (MCP) server for querying Sumo Logic logs. Enables AI-powered coding assistants to search and investigate application logs directly from your editor.

Works with any MCP-compatible client: Kiro, Claude Code, Cursor, VS Code + Copilot, and others.

Why This Project?

As of now July 31, 2026 - Sumo Logic has announced an MCP server as part of their Dojo AI platform (limited beta, focused on security operations), but there is no publicly available, standalone MCP server for general log search. Community options exist but tend to be minimal wrappers around the search API without attention to:

• Credential safety — this server redacts access keys from all error output and never logs credentials
• Cookie handling — Sumo's Search Job API requires cookies to be maintained per session; most implementations miss this and get intermittent failures
• Timestamp format — Sumo rejects ISO-8601 timestamps with milliseconds; this server sends epoch milliseconds correctly
• Job isolation — only search jobs created by this process can be queried or cancelled, preventing cross-session leakage
• Opinionated tools — sumo_find_errors and sumo_search_correlation_id encode common investigation patterns so your AI assistant doesn't need to know Sumo query syntax to be useful

If one of the community servers covers your needs, use it. This one prioritizes correctness and security for production use.

Quick Start

Prerequisites

• Node.js 20 or later
• A Sumo Logic account with an Access Key

Install Node.js

macOS (Homebrew):

brew install node@20

Or download from https://nodejs.org (LTS version).

Windows:

Option A — Download the installer from https://nodejs.org (LTS version). Run it and accept defaults.

Option B — Using winget:

winget install OpenJS.NodeJS.LTS

Option C — Using nvm-windows:

nvm install 20
nvm use 20

After installing, open a new terminal and verify:

node --version   # Should show v20.x.x or later
npm --version    # Should show 10.x or later

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

1. Create your Sumo Logic Access Key

1. Log into Sumo Logic
2. Click your username (bottom-left) and select Personal Access Keys (docs)
3. Click + Add Access Key
4. Name it something like "MCP Server"

Access keys can be scoped to limit permissions. When creating the key, select Custom scopes and enable only Log Search — that's the single scope this server needs. No other permissions are required.

The user creating the key must have a role with:

• A search filter that allows access to the log data you want to query

The built-in Analyst role works. If you want a minimal custom role, grant View Collectors, set the search filter to allow the source categories you need, and leave everything else unchecked.

Note: The Search Job API requires an Enterprise-tier Sumo Logic account. Free, Professional, and Essentials plans will get a 403 error. (docs)

2. Connect to your MCP client

Add the server to your client's MCP configuration. No install command is needed — your MCP client downloads the package automatically on first use.

• Kiro — .kiro/settings/mcp.json
• Claude Code — claude_code_config.json
• Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "sumo-mcp-readonly": {
      "command": "npx",
      "args": ["-y", "sumo-mcp-readonly"],
      "env": {
        "SUMO_ACCESS_ID": "your-access-id",
        "SUMO_ACCESS_KEY": "your-access-key",
        "SUMO_API_BASE_URL": "https://api.sumologic.com/api"
      }
    }
  }
}

Security note: If your client supports environment variable references (e.g., ${SUMO_ACCESS_ID}), prefer those over embedding credentials directly in config files. Set the variables in your shell profile instead.

Tools

Once connected, your MCP client can use these tools:

sumo_search_logs

Run any Sumo Logic query. This is the most flexible tool — anything you can type in the Sumo Logic search bar works here.

{
  "query": "_sourceCategory=prod/api status=500 | count by _sourceHost",
  "lastMinutes": 30,
  "limit": 50
}

Supports explicit time ranges too:

{
  "query": "error | count by _sourceCategory",
  "startTime": "2025-01-15T10:00:00Z",
  "endTime": "2025-01-15T11:00:00Z"
}

sumo_find_errors

Opinionated error search — looks for ERROR, exception, failure, fatal, and stack traces without needing to write the full query.

{
  "sourceCategory": "prod/api",
  "service": "user-service",
  "lastMinutes": 30,
  "text": "NullPointerException"
}

sumo_search_correlation_id

Search for a trace ID, request ID, or correlation ID across your logs. The ID is safely escaped as a literal.

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceCategory": "prod/api",
  "lastMinutes": 60
}

sumo_get_search_status

Check the status of a running search job. Only jobs created in the current session can be queried.

{
  "jobId": "IUUQI-DGH5I-TJ045"
}

sumo_cancel_search

Cancel a running search job. Only jobs created in the current session can be cancelled.

{
  "jobId": "IUUQI-DGH5I-TJ045"
}

Configuration Reference

All configuration is via environment variables. Copy .env.example to .env for local development, or pass them via your MCP client's env block.

Variable	Required	Default	Description
SUMO_ACCESS_ID	Yes	—	Sumo Logic Access ID
SUMO_ACCESS_KEY	Yes	—	Sumo Logic Access Key
SUMO_API_BASE_URL	Yes	—	Regional API endpoint (see below)
SUMO_DEFAULT_SOURCE_CATEGORY	No	—	Default _sourceCategory for opinionated tools
SUMO_MAX_QUERY_RANGE_MINUTES	No	1440	Maximum allowed query time range in minutes
SUMO_MAX_RESULT_COUNT	No	1000	Maximum results returned per query
SUMO_QUERY_TIMEOUT_SECONDS	No	120	Timeout waiting for search job completion
LOG_LEVEL	No	info	Log verbosity (debug, info, warn, error)

Determine Your API Endpoint

Your SUMO_API_BASE_URL must match your Sumo Logic deployment region. Look at the URL in your browser when logged into Sumo Logic:

If your URL contains	Your deployment	API Base URL
service.sumologic.com	US1	https://api.sumologic.com/api
service.us2.sumologic.com	US2	https://api.us2.sumologic.com/api
service.eu.sumologic.com	EU	https://api.eu.sumologic.com/api
service.au.sumologic.com	AU	https://api.au.sumologic.com/api
service.jp.sumologic.com	JP	https://api.jp.sumologic.com/api
service.ca.sumologic.com	CA	https://api.ca.sumologic.com/api
service.de.sumologic.com	DE	https://api.de.sumologic.com/api
service.in.sumologic.com	IN	https://api.in.sumologic.com/api
service.fed.sumologic.com	FED	https://api.fed.sumologic.com/api

Custom/vanity URLs (e.g., yourcompany.sumologic.com) are typically on US1. If you get HTTP 301 errors, you're using the wrong endpoint.

Security Model

This server is deliberately minimal and read-only:

• Read-only — only log search operations are supported
• No administration — no collector, user, role, token, partition, or source management
• No content mutation — no creation, deletion, or modification of Sumo Logic resources
• No shell execution — no arbitrary command execution
• No persistent storage — query results are not stored to disk
• Credentials never logged — access keys are redacted from all log output
• Job isolation — only search jobs created by this process can be queried or cancelled

WARNING: Sumo Logic query results may contain PII, secrets, API keys, or other sensitive data depending on what your applications log. Only use this server with MCP clients connected to AI services you trust with your log data.

Troubleshooting

401 Unauthorized — Your Access ID or Key is wrong, revoked, or expired. Double-check both values.

403 Forbidden — The access key's role doesn't have "Run Log Search" capability.

301 Redirect — Wrong regional API endpoint. See the table above. The URL must NOT end with a trailing slash.

Timeout — Increase SUMO_QUERY_TIMEOUT_SECONDS, narrow your time range, or simplify the query. Large searches can take minutes.

400 Bad Request — Query syntax error. Check your Sumo Logic query syntax and field names.

429 Rate Limited — Sumo Logic allows 4 requests/second per user and 200 concurrent jobs per org. Reduce query frequency.

Credential Rotation

1. Create a new access key in Sumo Logic (Administration > Security > Access Keys)
2. Update SUMO_ACCESS_ID and SUMO_ACCESS_KEY in your .env or MCP client config
3. Restart the MCP server (your client will do this automatically on config change)
4. Verify with a simple query
5. Revoke the old key in Sumo Logic

Development

npm run dev          # Run with tsx (no build step needed)
npm run build        # Compile TypeScript
npm test             # Run unit tests (68 tests)
npm run test:watch   # Watch mode
npm run lint         # ESLint
npm run format       # Prettier
npm run format:check # Check formatting without writing

Architecture

src/
  index.ts            — Entry point, config validation, server startup
  server.ts           — MCP server creation and tool registration
  config.ts           — Environment variable validation (Zod)
  logging.ts          — Structured JSON logger (stderr only)
  sumo/
    client.ts         — HTTP client with auth, cookies, error mapping
    auth.ts           — HTTP Basic authentication header
    types.ts          — Sumo Logic API type definitions
    search-jobs.ts    — Search lifecycle orchestration
    errors.ts         — Typed error hierarchy
  tools/
    search-logs.ts    — sumo_search_logs implementation
    find-errors.ts    — sumo_find_errors implementation
    search-correlation-id.ts — sumo_search_correlation_id implementation
    get-search-status.ts     — sumo_get_search_status implementation
    cancel-search.ts         — sumo_cancel_search implementation
  query/
    escaping.ts       — Query literal escaping
    builders.ts       — Opinionated query construction
  security/
    redaction.ts      — Credential redaction for error output
    limits.ts         — Time range and result count enforcement

License

MIT