Summary: smart-glitchtip-mcp is a read-only-by-default MCP server that exposes a GlitchTip instance's API (~130 tools across 18 toolsets) to AI agents like Claude Code, Codex and Cursor, over stdio or stateless HTTP.
Triage errors: list, search, filter and update issues (status, assignment, merge, bulk updates, comments, tags, hashes, user reports); fetch issue/project events, the latest event and raw event JSON (PII-redacted).
Inspect projects and orgs: list organizations (slug, name, created), get one organization with its projects, teams and your access scopes, list organization environments, and manage projects, client keys (DSN), environments and project teams.
Track releases: releases, deploys, commits, release files and repositories.
Manage alerting and uptime: project alert rules and recipients, uptime monitors and checks, status pages.
Performance and logs: transactions, spans, N+1 patterns, logs and organization stats.
Admin and billing: current user (whoami), notification settings, license, usage and plans, test events.
Uploads (stdio only): debug files, artifact bundles and ProGuard mappings.
Escape hatch: api_get plus a gated api_request for endpoints without a dedicated tool.
Prompts and resources: triage-issue and release-health-report prompts; glitchtip://issues/... resource templates to attach an issue or event to a conversation.
Safety and control: read-only by default (write/delete tools only registered with GLITCHTIP_READ_ONLY=false), toolsets enabled per deployment via GLITCHTIP_TOOLSETS, compact token-budgeted output, token scrubbing, and untrusted sender text fenced against prompt injection.
Deployment options: stdio for local agents (one process per developer) or shared Streamable HTTP at POST /mcp with per-caller GlitchTip tokens, MCP_AUTH_TOKEN shared secret, GET /healthz, and allowlisted multi-instance selection via X-GlitchTip-Url.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@smart-glitchtip-mcp show unresolved issues in the acme-web project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI agents the whole of GlitchTip — triage, releases, alerts, uptime and more — over MCP.
Your agent can read a stack trace in your editor, but the error tracker stays a browser tab away: it cannot list the issues behind a spike, open the latest event, check what a release broke or resolve what it fixed. smart-glitchtip-mcp is a Model Context Protocol server that puts a GlitchTip instance's API in front of any MCP client — Claude Code, Codex, Cursor and others — as typed tools with compact, token-safe output. It is read-only unless you switch writes on.
Who it is for: teams that self-host GlitchTip (or use its hosted service) and want coding agents to investigate and manage errors without copy-pasting from the web UI.
About 130 tools in 18 toolsets covering the GlitchTip 6.2.6 API:
organizations, issues, events, projects, teams, members,
releases, alerts, monitors, status_pages, performance, logs,
stats, admin, billing, ingest, uploads and an api_request escape
hatch. Each is documented in docs/tools/.
Read-only by default. Tools that change or delete data are not even
registered unless GLITCHTIP_READ_ONLY=false; toolsets are switched on per
deployment with GLITCHTIP_TOOLSETS.
stdio and stateless Streamable HTTP — one process per developer, or one shared server for a team, where each caller can bring their own GlitchTip token.
Safe output for agents. Results are compact text (or JSON) bounded by a size budget; the API token is scrubbed from every result, log and error; and text that comes from event senders (titles, messages, tags) is fenced as untrusted so an agent does not follow instructions hidden in it.
Prompts and resources. triage-issue and release-health-report
prompts, and glitchtip://issues/... resource templates to attach an issue or
event to a conversation.
Several instances. Over HTTP a caller can pick another allowlisted instance with a header; anything outside the allowlist is refused.
Related MCP server: Cursor Cloud MCP
Requirements: Node.js 24 or later. The server is published on npm as
smart-glitchtip-mcp, so
npx runs it without a clone:
npx -y smart-glitchtip-mcpOr install it globally with npm i -g smart-glitchtip-mcp and run
smart-glitchtip-mcp. To build it from source instead, see
Development.
Create an API token in GlitchTip (Profile → Auth Tokens) with the scopes
the toolsets you enable need — each file in docs/tools/ lists
them.
Add the server to your MCP client configuration, for example:
{
"mcpServers": {
"glitchtip": {
"command": "npx",
"args": ["-y", "smart-glitchtip-mcp"],
"env": {
"GLITCHTIP_URL": "https://glitchtip.example.com",
"GLITCHTIP_TOKEN": "<api token>"
}
}
}
}With Claude Code:
claude mcp add glitchtip \
-e GLITCHTIP_URL=https://glitchtip.example.com \
-e GLITCHTIP_TOKEN=<api token> \
-- npx -y smart-glitchtip-mcpstdout carries only MCP messages; logs go to stderr. Then ask the agent, for
example, "list the unresolved issues in project web from the last 24 hours
and triage the top one".
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
GLITCHTIP_URL=https://glitchtip.example.com \
npx -y smart-glitchtip-mcpThe MCP endpoint is POST /mcp (stateless Streamable HTTP; no session ids).
GET /healthz answers ok without authentication. Every MCP request must carry
Authorization: Bearer <token>, otherwise it gets 401:
Your own GlitchTip token as the bearer: the server forwards it to GlitchTip, which decides what you may do.
MCP_AUTH_TOKEN as the bearer: the server acts with its own
GLITCHTIP_TOKEN. A server holding GLITCHTIP_TOKEN refuses to start in HTTP
mode unless MCP_AUTH_TOKEN is set, so the token is never open to anyone who
can reach the port.
Optional request headers:
Header | Meaning |
| Another GlitchTip instance to act on. Only with your own token, and only when it is |
| Default organization slug for this request. |
docker build -t smart-glitchtip-mcp .
docker run --rm -p 8080:8080 \
-e GLITCHTIP_URL=https://glitchtip.example.com \
-e GLITCHTIP_TOKEN=<api token> \
-e MCP_AUTH_TOKEN=<a random 16+ character secret> \
smart-glitchtip-mcpThe image defaults to HTTP on port 8080. stdio, docker compose for
development and the release pipeline are described in
docs/deployment.md.
All configuration comes from environment variables. Invalid configuration stops startup with one line per problem on stderr, naming the variable (never its value), and exit code 1.
Variable | Type / default | Meaning |
|
| transport |
| int, default | HTTP port |
| default | endpoint path |
| string, optional; at least 16 characters, no whitespace | shared secret for HTTP clients that do not bring their own GlitchTip token; required in HTTP mode when |
| URL, required in stdio; optional in http | default instance |
| string, optional | default token |
| slug, optional | default organization |
| comma list of origins, default empty | other instances an HTTP client may select with |
| comma list, default | enabled toolsets |
| bool, default |
|
| int, default | timeout of each request to GlitchTip |
| int chars, default | maximum size of a tool result; longer results are truncated and say so — |
| pino level, default | log level (logs go to stderr; HTTP request lines carry method, path and a short list of harmless headers, never credentials) |
Known toolsets: organizations, issues, events, projects, teams,
members, releases, alerts, monitors, status_pages, performance,
logs, stats, admin, billing, ingest, uploads, api_request. A known
toolset that is not implemented yet is accepted and logged as "not yet
available"; an unknown name stops startup.
Requests to GlitchTip time out after GLITCHTIP_TIMEOUT_MS. Reads are retried
up to twice on 429, 5xx and network errors, honouring Retry-After; writes are
never retried.
whoami is always available and shows the instance, user and token scopes in
use. Everything else comes in toolsets, enabled with GLITCHTIP_TOOLSETS
(default organizations,issues,events,projects, or all):
Toolset | What it covers |
organizations and their environments | |
list, search, status, assignment, merge, bulk updates, comments, tags, hashes, user reports | |
issue and project events, the latest event, raw event JSON (PII-redacted) | |
projects, client keys (DSN), environments, project teams | |
teams, team membership, organization members and roles | |
releases, deploys, commits, release files, repositories | |
project alert rules and recipients | |
uptime monitors, checks, status pages | |
transactions, spans, N+1 patterns, logs, organization stats | |
current user, notification settings, license, usage and plans, test events | |
debug files, artifact bundles, ProGuard mappings (stdio only) | |
|
Two MCP prompts, triage-issue and release-health-report, guide an agent
through a read-only task with these tools
(docs/tools/prompts.md); each is listed only when
every toolset it uses is enabled. Two resource templates,
glitchtip://issues/{issue_id}{?organization} and
glitchtip://issues/{issue_id}/events/{event_id}{?organization} (event_id may
be latest), attach an issue or an event to a conversation by URI
(docs/tools/resources.md).
agent ──MCP──▶ stdio | Streamable HTTP
▼
auth guard (HTTP only) → instance resolver (URL, token, org)
▼
toolset tool: zod input schema, read-only gate
▼
GlitchTip client (types generated from the API snapshot)
▼
compact, budgeted, token-scrubbed resultIt is a NestJS application on @rekog/mcp-nest.
The client is generated from a snapshot of the GlitchTip OpenAPI schema, and a
contract test fails if a snapshot refresh drops an endpoint the tools call. Details are in
docs/architecture.md, and every design choice, with
the alternatives rejected, is in docs/decisions.md.
bun install
bun run lint
bun run typecheck
bun run test # unit, contract, protocol, HTTP and process tests; no network
bun run build
bun run test:e2e # against a real instance; needs E2E_GLITCHTIP_URL, _TOKEN, _ORG
bun run api:generate # regenerate src/glitchtip/generated from the API snapshotbun run dev rebuilds and restarts on change; docker compose up does the same
in a container pointed at the instance in .env (copy
.env.example first).
docs/ is the authority on what the server does and why.
Path | What lives there |
one file per toolset: tools, inputs, annotations, token scopes | |
design decisions | |
the request path and the source layout | |
Docker, Woodpecker CI, cutting a release | |
the backlog and its state | |
one specification per change |
Read AGENTS.md first. Work is tracked as FEAT-/BUG- IDs and
lands on develop; main carries releases only.
Get one organization: slug, name, its projects and teams (counts and slugs), and the access scopes you hold in it. Scope: org:read, org:write or org:admin.
Inputs: format, organization.
List environment names used in an organization's events (e.g. production, staging). Scope: org:read, org:write or org:admin.
Inputs: limit, cursor, format, visibility, +1 more.
List organizations the token can see, with slug, name and creation date. Scope: org:read, org:write or org:admin.
Inputs: limit, cursor, format.
Show which GlitchTip instance and user this server is acting as, the instance version, and the scopes of the token in use. Call this first when a tool fails with a permission error. Needs no scope.
Inputs: format.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool targets a distinct concern: whoami handles identity/permissions, list_organizations provides an overview, get_organization drills into a single org's details, and list_organization_environments focuses on a specific attribute. There is no meaningful overlap or ambiguity between them.
All tools use snake_case and follow a clear verb_noun pattern (list_*, get_*). whoami is a standard, recognizable exception that still fits the command-style naming. The convention is consistent and predictable.
With only 4 tools, the server is tightly scoped to read-only organization exploration. Each tool adds distinct value without bloat, and the count is well within the ideal range for a focused MCP server.
The surface covers the essential read paths: identity check, list organizations, retrieve a single organization, and list environments. Missing mutation (create/update/delete) and deeper project/team detail tools, but the server appears intentionally read-only for this niche. Minor gaps exist but agents can complete basic workflows.
Production errors and incidents for your agent: stack traces, breadcrumbs, likely causes, triage.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Investigate errors, track deployments, analyze performance, and manage application monitoring
Production errors your coding agent can read: search, stack traces, context, trends, resolve.
