faultline-mcp

Model Context Protocol server for Faultline — lets AI agents (Claude Desktop, Claude Code, Cursor, and any MCP client) operate your Faultline monitoring and incident response.

npx faultline-mcp

Why

Faultline watches your infrastructure; this server lets an AI agent watch Faultline. Once connected, an assistant can answer questions and take action against your live environment:

• "What's down right now, and who's on call?"
• "Why is checkout-api degraded?" — pulls recent health checks and latency anomalies.
• "Acknowledge incident clx9… so it stops escalating."
• "Diagnose the database incident and run the restart runbook if you're confident."

The server exposes a small, prescriptive toolset over Faultline's /agent API. Tool descriptions tell the model when to call each tool, which is what drives correct behavior — read-only inspection is free, while mutating actions (resolve, run runbook) are clearly marked so the agent confirms with you first.

Installation

The server is distributed on npm and runs over stdio — most MCP clients launch it for you via npx, so there's nothing to install globally.

Requires Node.js 18 or later (uses the built-in fetch API).

Authentication

The server authenticates with a Faultline API key, the same keys used by the CLI and the /ingest API. Generate one in the dashboard under Settings → API Keys.

Configuration comes entirely from two environment variables, passed by your MCP client:

| Variable | Required | Description | |---|---|---| | FAULTLINE_API_KEY | yes | Your API key (flt_...). The server exits on startup if it's missing. | | FAULTLINE_API_URL | no | API base URL. Defaults to https://api.fltln.io. |

The key is sent as the X-API-Key header. Scope it to a single service or leave it tenant-wide depending on how much of your infrastructure the agent should see.

Setup

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "faultline": {
      "command": "npx",
      "args": ["-y", "faultline-mcp"],
      "env": {
        "FAULTLINE_API_KEY": "flt_your_key_here",
        "FAULTLINE_API_URL": "https://api.fltln.io"
      }
    }
  }
}

Restart Claude Desktop. The Faultline tools appear in the tools menu.

Claude Code

claude mcp add faultline \
  --env FAULTLINE_API_KEY=flt_your_key_here \
  --env FAULTLINE_API_URL=https://api.fltln.io \
  -- npx -y faultline-mcp

Cursor / other MCP clients

Any client that speaks MCP over stdio works. Point it at the npx -y faultline-mcp command and pass the two environment variables above.

Tools

Eleven tools, grouped by what they touch. Read-only tools are safe to call freely; mutating tools change live state and should run only after the user confirms.

Inspect (read-only)

| Tool | Arguments | What it does | |---|---|---| | list_services | status? | List all monitored services and their status (OK, DEGRADED, DOWN, PAUSED, PENDING). The starting point for an infrastructure overview or to find a service ID. | | get_service | serviceId | One service's details plus its 10 most recent health checks (status codes, latency, errors). Used to diagnose why a service is degraded. | | list_incidents | status? | List incidents — open by default, or resolved for recent history. | | get_incident | incidentId | An incident's full record: timeline, escalations, runbook results, AI summary, post-mortem. | | who_is_on_call | — | The person currently on call for each schedule and when their shift ends. | | list_anomalies | — | Recent learned-baseline latency anomalies: observed vs. baseline response time, z-score, sustained duration, and any auto-opened incident. Early degradation signals before a hard up/down threshold trips. | | diagnose_incident | incidentId | Analyze an open incident and recommend the next action (run a runbook, escalate, resolve, or wait) with rationale, confidence, and candidate runbooks. Analysis only — changes nothing. |

Act (mutating)

| Tool | Arguments | What it does | |---|---|---| | acknowledge_incident | incidentId | Acknowledge an open incident, stopping further escalation. | | resolve_incident | incidentId, note? | Mark an incident resolved with an optional fix note. Status-page-visible. | | run_runbook | incidentId, runbookId | Execute one runbook against an incident. Mutates infrastructure (can restart or scale services). Intended to run only after diagnose_incident recommends it and the user confirms. |

A typical remediation flow: list_incidents → get_incident → diagnose_incident → (user confirms) → run_runbook → resolve_incident.

How it works

The server is a thin, dependency-light wrapper (built on global fetch, Node 18+) around Faultline's /agent REST API. It speaks MCP over stdio — stdout carries the protocol, so all logging goes to stderr. API errors are returned to the agent as readable tool errors rather than crashing the process, so the model can adapt and retry.

Troubleshooting

| Symptom | Cause / fix | |---|---| | FAULTLINE_API_KEY is required on startup | The env var isn't reaching the server. Confirm it's set in your MCP client's env block. | | Faultline API 401 | Invalid or revoked API key. Generate a new one under Settings → API Keys. | | Faultline API 403 on a service or incident | The key is scoped narrower than the resource you're asking about. Use a tenant-wide key or the correct service-scoped key. | | Tools don't appear in the client | Restart the client after editing its config; make sure Node 18+ is on PATH. |

License

MIT