This server exposes GlitchTip functionality to an MCP agent (read-only by default), currently offering organization-level tools plus identity/environment info.
whoami: show which GlitchTip instance and user you are acting as, instance version, and token scopes.
list_organizations: list organizations the token can see, with slug, name, and creation date (paginated).
get_organization: get one organization's slug, name, projects, teams, and your access scopes in it.
list_organization_environments: list environment names used in an organization's events (visible, hidden, or all; paginated).
Additional toolsets (issues, events, projects, releases, alerts, monitors, performance, etc.) can be enabled by configuration; writes are off unless read-only mode is disabled.
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.
An MCP server that gives agents the full working surface of a GlitchTip instance — issues, events, projects, releases, alerts, uptime monitors, performance and more. Point it at an instance URL with an API token.
Status: foundation in place (transports, auth, the GlitchTip client, the
organizationstoolset). Further toolsets land perdocs/roadmap.md.
NestJS + @rekog/mcp-nest
stdio and stateless Streamable HTTP
read-only by default; toolsets switched on per deployment
targets GlitchTip 6.2.6
Requires Node.js 24 or later.
GLITCHTIP_URL=https://glitchtip.example.com \
GLITCHTIP_TOKEN=<api token> \
npx smart-glitchtip-mcpFor example, in an MCP client configuration:
{
"mcpServers": {
"glitchtip": {
"command": "npx",
"args": ["smart-glitchtip-mcp"],
"env": {
"GLITCHTIP_URL": "https://glitchtip.example.com",
"GLITCHTIP_TOKEN": "<api token>"
}
}
}
}stdout carries only MCP messages; logs go to stderr.
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
GLITCHTIP_URL=https://glitchtip.example.com \
npx 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. |
Related MCP server: GenieOS MCP Server
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. Other tools come in toolsets, each documented in
docs/tools/:
Two MCP prompts guide an agent through a read-only task with the tools above,
documented in docs/tools/prompts.md: triage-issue
and release-health-report. Each is listed only when every toolset its steps
use is enabled and available.
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 snapshotRead AGENTS.md first. Work is tracked as FEAT-/BUG- IDs and
lands on develop; main carries releases only.
Apache-2.0
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.
Observability for AI apps: investigate traces, logs, LLM usage, replays and crashes; manage alerts.
