@inso_web/els-mcp

🇷🇺 Документация на русском: docs/README.ru.md

MCP connector for INSO Event Logs Service. Plug Claude Desktop, Cursor, Windsurf, ChatGPT or any other AI agent into your application's error logs — for search, analysis, correlations and fast triage.

The service is cloud-hosted on INSO infrastructure. This package is only needed for clients that prefer connecting over stdio. If your client supports Streamable HTTP — you don't need to install anything at all, see below.

• Service homepage: https://mcp.insoweb.ru/els/
• Customer portal (API keys): https://lk.insoweb.ru

Quick start

Step 1. Get an API key

Open the customer portal, create an API key with the errors:mcp-read scope. The key looks like els_live_xxxxxxxxxxxxxxxx.

Step 2. Connect the connector

Option A — cloud endpoint (recommended)

Works with most modern MCP clients: Cursor, Windsurf, Zed, Claude Code, ChatGPT Custom Connectors, Claude Desktop ≥ 0.9.

In the client's settings add:

{
  "mcpServers": {
    "els": {
      "url": "https://mcp.insoweb.ru/els/mcp",
      "headers": {
        "Authorization": "Bearer els_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart the client — ELS tools will appear in the tool list. Nothing is installed on your machine.

Option B — via npx (for clients without HTTP transport)

If your client currently supports only stdio (older Claude Desktop, some corporate builds):

{
  "mcpServers": {
    "els": {
      "command": "npx",
      "args": ["-y", "@inso_web/els-mcp"],
      "env": {
        "ELS_API_KEY": "els_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

npx will fetch the package on first run. No global installs.

Step 3. Verify the connection

Ask your agent: "show me the last 10 errors over the past hour". If the ELS tools are wired up correctly, it will reach the cloud and return a result.

Available tools

18 read-only tools cover search, analytics, fingerprinting, correlations, regression detection and AI triage. The MCP layer never writes or modifies data.

Quick grouping:

• Search & details: search_logs, get_log_details, query_logs_jql, errors_in_session
• Analytics & trends: top_error_messages, error_histogram, error_heatmap, traffic_stats, error_stats_breakdown
• Grouping & correlation: find_similar_errors, find_correlated_errors, grouped_errors
• Impact & regression: impact_analysis, baseline_compare, version_regression
• Triage & AI: triage_recent_critical, explain_error, list_apps

Full reference with parameter descriptions and example prompts for AI agents:

• English: docs/TOOLS.md
• Русский: docs/TOOLS.ru.md

Project context (optional)

To let the agent automatically know which application each query refers to, drop an els.config.json file into your repository root:

{
  "$schema": "https://mcp.insoweb.ru/els/schema/els.config.schema.json",
  "appSlug": "my-app",
  "environments": {
    "dev": "DEV",
    "production": "PRODUCTION"
  },
  "defaultEnvironment": "production",
  "alerts": {
    "criticalRateThreshold": 5
  }
}

Once present, the agent will:

• automatically pass appSlug to every tool,
• know which environments you operate,
• proactively run standard workflows: check DEV logs after a feature, take a baseline before deploy, compare against baseline after.

Alternative: an inso.els section right inside package.json — same format.

Response formats and pagination

Every listing tool accepts a response_format parameter:

• compact (default) — no stack, componentStack, userAgent, message capped at 200 characters. Cheap on LLM tokens.
• full — every field.
• summary — only traceId, message, level, lastSeen.

Page traversal uses an opaque cursor (not page/offset). The cursor carries a hash of the current filters; if you change a filter between pages, the server returns INVALID_ARGS and asks you to start over.

Data safety

Every response runs through a PII-redaction pipeline before reaching the LLM:

• IPv4 — last octet zeroed (192.168.1.42 → 192.168.1.0)
• IPv6 — only /64 prefix preserved
• Email, phone numbers, card numbers (Luhn-validated), JWTs and Bearer tokens are replaced with […_REDACTED]
• URLs and referrers strip the query string
• User-Agent is collapsed to browser family

User-supplied content from logs (message, stack) is wrapped in <untrusted>…</untrusted> tags to mitigate prompt injection.

Plan limits

| Tier | Requests / day | Concurrent SSE | AI-explain / day | |---|---|---|---| | Free | 1 000 | 2 | 20 | | Standard | 50 000 | 20 | 500 | | Premium | 500 000 | 100 | 5 000 | | Unlimited | ∞ | 500 | ∞ |

On overuse the server returns TIER_QUOTA_EXCEEDED with retryAfter counting down to midnight UTC. There's a 10 % grace zone (_meta.overage = true).

Error codes

RATE_LIMITED, UPSTREAM_UNAVAILABLE, INVALID_ARGS, NOT_FOUND, INSUFFICIENT_SCOPE, QUOTA_EXCEEDED, INTERNAL.

Environment variables

The only required one is ELS_API_KEY. The rest have sensible defaults.

| ENV | Default | Description | |---|---|---| | ELS_API_KEY | — | API key (els_live_* or els_test_*) | | ELS_BASE_URL | https://api.insoweb.ru/els | ELS API endpoint | | MCP_LOG_LEVEL | info | Log level (pino) | | MCP_DISABLE_TOOLS | — | CSV of tool names to disable | | MCP_UPSTREAM_TIMEOUT_MS | 30000 | Single ELS-request timeout |

Support

• Documentation and updates: https://mcp.insoweb.ru/els/
• Customer portal, keys, billing: https://lk.insoweb.ru
• Team contact: https://insoweb.ru

Package development

Contributor docs and local-run scenarios: CONTRIBUTING.md.

License

MIT