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: TypeSafe 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.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text (default): compact, for reading. json: the same fields as JSON, for further processing. | text |
| organization | No | Organization slug. Optional: defaults to the server or header default, or to the only organization the token can see. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the required OAuth scopes (org:read, org:write, or org:admin) and the composition of the response (slug, name, projects and teams counts/slugs, access scopes). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence front-loads the operation and return payload, and the second specifies the access scopes. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 optional params, no output schema). The description covers the return payload and the authorization requirement, which are the most important operational facts. The format parameter and optionality of organization are already documented in the schema, so nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents both 'format' and 'organization'. The description adds no parameter-level meaning beyond that schema, meriting the baseline 3 for fully covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'one organization' and enumerates the exact returned data: slug, name, projects/teams counts and slugs, and access scopes. This clearly distinguishes it from siblings like list_organizations (plural) and whoami. A tool name alone would be ambiguous, but the description removes that ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need details of a single organization rather than a list. It provides a clear context by specifying the return fields and required scopes. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List environment names used in an organization's events (e.g. production, staging). Scope: org:read, org:write or org:admin.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1–100 (default 50). | |
| cursor | No | Cursor from the previous page ("next cursor: …"); omit for the first page. | |
| format | No | text (default): compact, for reading. json: the same fields as JSON, for further processing. | text |
| visibility | No | Which environments to list: visible (default), hidden, or all. | visible |
| organization | No | Organization slug. Optional: defaults to the server or header default, or to the only organization the token can see. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation read-only and idempotent; the description adds useful non-annotated context by defining the data source ('organization's events') and the required permission scope. It does not discuss return format or pagination, but those are covered in the parameter schema, and nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the purpose front-loaded and a concise scope note; every sentence adds distinct information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with 5 optional, fully-documented parameters and rich annotations, the description plus schema cover what the agent needs: what is listed, the auth scope, and all call options. Output shape is implied by 'environment names' and the format parameter, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (limit, cursor, format, visibility, organization) already has detailed semantics including defaults, enums, and patterns. The description adds no parameter-level information, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb and resource ('List environment names used in an organization's events') and gives concrete examples (production, staging). It clearly differentiates from sibling tools like list_organizations and get_organization, which operate on organizations rather than their environments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for listing environment names within an organization's events and states the required scope (org:read, org:write or org:admin). It does not explicitly name alternative siblings for when-not-to-use, but the context is unambiguous and there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List organizations the token can see, with slug, name and creation date. Scope: org:read, org:write or org:admin.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1–100 (default 50). | |
| cursor | No | Cursor from the previous page ("next cursor: …"); omit for the first page. | |
| format | No | text (default): compact, for reading. json: the same fields as JSON, for further processing. | text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations by specifying the required OAuth scopes and the fields returned, which helps an agent understand access and output expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The action and resource are front-loaded, and the scope information is included without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with rich annotations and fully described optional parameters, the description plus schema covers visibility scope, return fields, and pagination/format. No output schema exists, but the description states the returned fields, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (limit, cursor, format) are already fully documented. The description adds no parameter-level detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: lists organizations visible to the token, with the returned fields slug, name, and creation date. This clearly distinguishes it from get_organization (single organization) and list_organization_environments (environments within an organization).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides scope prerequisites (org:read, org:write, or org:admin) but gives no explicit guidance on when to choose this tool over its siblings. An agent must infer from sibling names when this list operation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text (default): compact, for reading. json: the same fields as JSON, for further processing. | text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, idempotent, and non-destructive. The description adds meaningful context by clarifying that it needs no scope and by positioning it as a diagnostic first step, which is useful beyond the structured annotation data. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler: the first states what the tool shows, and the second gives one actionable usage instruction. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-required-parameter, read-only tool, the description covers what it returns, when to call it, and the auth prerequisite. The schema covers the optional format switch, and the annotations cover the safety profile, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, format, is fully documented in the input schema with enum values, a default, and an explanation of text versus json output. With 100% schema description coverage, the description does not need to add parameter detail; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and names the exact resource and outputs: the GlitchTip instance, acting user, instance version, and token scopes. This clearly distinguishes it from the sibling resource-listing tools such as list_organizations and get_organization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to call this tool first ('when a tool fails with a permission error') and notes that no scope is required. It does not name alternatives or when-not cases, but for this identity/diagnostic tool that is a minor omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_organizationlist_organization_environmentslist_organizationswhoamiScored 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.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Investigate errors, track deployments, analyze performance, and manage application monitoring
Operate smplkit from your agent: feature flags, config, logging, audit, and scheduled jobs.
Error tracking for Laravel and PHP apps. Let your agent fetch errors, stack traces and context.
