# segi · Read API + MCP server · LLM integration guide

`@extn/segi-mcp` is a read-only MCP (Model Context Protocol) server that lets
an AI coding agent — Claude Code, Claude Desktop, Cursor, or anything
MCP-aware — read a segi organization's error data (projects, issues, events,
stack traces, stats) and fix the bugs in the customer's own codebase.

This is different from `@extn/segi-mcp-nextjs` / `@extn/segi-mcp-nestjs`
(setup helpers that describe how to install the SDK). This server reads
**live monitoring data** using an organization API key.

## TL;DR

1. In the segi console: **Organization → API keys** → create a key
   (OWNER/ADMIN only). The plaintext `segi_sk_live_…` key is shown **once**.
2. Connect the agent:

```bash
claude mcp add segi -e SEGI_SECRET_KEY=segi_sk_live_xxx -- npx -y @extn/segi-mcp
```

3. Ask: "Look at the noisiest error in segi and fix the root cause here."

Self-hosted / staging: add `-e SEGI_API_URL=https://your-segi-api.example.com`.
Default API base is `https://segiapi.extn.ai`.

## MCP tools (8, all read-only)

- `list_projects()` — projects visible to the key.
- `get_overview()` — org-wide dashboard summary (24h/7d counts, top issues).
- `list_issues(projectId, status?, environment?, search?, from?, to?, page?, pageSize?)`
  — grouped issues; `search` is a substring match on title/message/culprit.
- `get_issue(projectId, issueId)` — one issue with metadata + counts.
- `get_issue_events(projectId, issueId, page?, pageSize?)` — raw events of an issue.
- `search_events(projectId, level?, environment?, transaction?, search?, from?, to?, page?, pageSize?)`
  — search raw events project-wide.
- `get_event(projectId, eventId)` — full event incl. stack trace, breadcrumbs,
  request context. `eventId` is the event's string id, not the numeric row id.
- `get_project_stats(projectId)` — summary + timeseries for one project.

`from`/`to` are ISO-8601. `pageSize` max 100, default 20.

## Underlying REST API (if you'd rather curl)

All endpoints: `Authorization: Bearer segi_sk_live_…`, JSON responses, GET only.

```
GET https://segiapi.extn.ai/api/mcp/v1/projects
GET https://segiapi.extn.ai/api/mcp/v1/overview
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/issues
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/issues/{issueId}
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/issues/{issueId}/events
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/events
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/events/{eventId}
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/summary
GET https://segiapi.extn.ai/api/mcp/v1/projects/{projectId}/timeseries
```

List filters are query params with the same names as the MCP tool arguments
(`status`, `environment`, `search`, `level`, `transaction`, `from`, `to`,
`page`, `pageSize`).

## Keys & security model

- Keys are **organization-scoped** and created in the console by an org
  OWNER or ADMIN (max 20 active keys per org). Optionally restricted to a
  single project at creation time.
- Only a SHA-256 hash is stored; the plaintext is shown once at creation.
  Losing it means creating a new key.
- Revocation (console → API keys → revoke) takes effect immediately.
- Per-key rate limit: 60 requests/minute by default (configurable at
  creation). Exceeding it returns `429`.
- Strictly read-only — there are no write tools or endpoints; the key cannot
  triage, resolve, or delete anything.
- Event responses omit `ipAddress` and `userEmailHash`; stack traces are
  capped at 20k chars and JSON blobs at 8k chars.

## Common errors

- `401 Invalid API key` — missing/typo'd/revoked key, or wrong `SEGI_API_URL`.
- `404 Not found` — projectId outside the key's organization (or its
  project scope). Existence is not disclosed.
- `429 Too many requests` — per-key per-minute rate limit hit; back off.

## See also

- Console key management: https://segi.extn.ai/organization/api-keys
- Setup-helper MCPs (install the SDK, not read data):
  `@extn/segi-mcp-nextjs`, `@extn/segi-mcp-nestjs` — see
  https://segi.extn.ai/llms/error-monitoring.txt