observability-mcp — Claude Code MCP server: setup guide
An observability gateway for AI agents that connects Prometheus, Loki, and topology tools through a single interface for incident triage.
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env PROMETHEUS_URL=<PROMETHEUS_URL> --env LOKI_URL=<LOKI_URL> --transport stdio observability-mcp -- npx -y @thotischner/observability-mcpWhat observability-mcp does
The server acts as a middle layer connecting AI agents to monitoring platforms like Prometheus and Loki. Instead of returning raw log dumps, the gateway filters and aggregates data on the server side. The agent receives clean summaries.
Specialized inspection calls like get_topology and get_blast_radius resolve dependencies between pods and cluster nodes. Every tool runs in read-only mode. That prevents the model from altering runtime infrastructure.
At startup, the gateway has zero configured backends. You configure data sources either through the browser UI on port 3000 or with PROMETHEUS_URL and LOKI_URL environment variables. Without those backends in place, the gateway cannot collect incident metrics.
What it helps with
- map co-located pods on a failing cluster node
- query Prometheus metrics with server-side aggregation
- calculate blast radius during a service outage
- inspect infrastructure topology using read-only agent tools
Example prompts for the agent
- Run
get_blast_radiusonpayment-serviceto see what pods share the node. - Check
get_topologyto find dependent services before restarting the deployment.
How to install observability-mcp
Platform CLI
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env PROMETHEUS_URL=<PROMETHEUS_URL> --env LOKI_URL=<LOKI_URL> --transport stdio observability-mcp -- npx -y @thotischner/observability-mcpReplace <…> with your own values
Platform CLI
codex mcp add observability-mcp --env MCP_TRANSPORT=<MCP_TRANSPORT> --env PROMETHEUS_URL=<PROMETHEUS_URL> --env LOKI_URL=<LOKI_URL> -- npx -y @thotischner/observability-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"observability-mcp": {
"command": "npx",
"args": [
"-y",
"@thotischner/observability-mcp"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"PROMETHEUS_URL": "<PROMETHEUS_URL>",
"LOKI_URL": "<LOKI_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"observability-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@thotischner/observability-mcp"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"PROMETHEUS_URL": "<PROMETHEUS_URL>",
"LOKI_URL": "<LOKI_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e PROMETHEUS_URL=<PROMETHEUS_URL> -e LOKI_URL=<LOKI_URL> observability-mcp npx -y @thotischner/observability-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about observability-mcp
How to install observability-mcp in Claude Code?
Run claude mcp add observability-mcp -- npx -y @thotischner/observability-mcp in your terminal.
What does observability-mcp do?
It routes queries across Prometheus and Loki into a normalized gateway, providing read-only topology and metric inspection tools for incident triage.
Does observability-mcp require preconfigured data sources?
The gateway boots with zero active sources. Connect Prometheus or Loki via the web UI on port 3000 or by setting the PROMETHEUS_URL and LOKI_URL variables.
