@inso_web/els-mcp
Version:
MCP-сервер поверх INSO Error Logs Service. Read-only tools (search, analytics, fingerprinting, correlations) для подключения Claude Desktop/Code и ChatGPT к логам ошибок. Streamable HTTP transport + stdio для npx-запуска.
203 lines (149 loc) • 6.12 kB
Markdown
# /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