# @inso_web/els-mcp

🇷🇺 **Документация на русском**: [docs/README.ru.md](https://unpkg.com/browse/@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](https://lk.insoweb.ru), 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:

```json
{
  "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):

```json
{
  "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](https://unpkg.com/browse/@inso_web/els-mcp/docs/TOOLS.md)
- Русский: [docs/TOOLS.ru.md](https://unpkg.com/browse/@inso_web/els-mcp/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:

```json
{
  "$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](https://unpkg.com/browse/@inso_web/els-mcp/CONTRIBUTING.md).

## License

MIT