[harisrujanc]

📑 Description

Adds keep-mcp, an MCP (Model Context Protocol) server shipped as an independent sidecar next to keep-backend, so LLM clients (Claude Desktop, Copilot CLI, Cursor, agent frameworks) can query Keep. It is a thin adapter over the Keep REST API: it stores no secrets or tenancy state and forwards X-API-KEY, so Keep stays the single source of truth for authZ/RBAC.

Closes #6618

Architecture

How to read it: orange = what this PR adds, white = existing Keep. Clients reach the sidecar over stdio (local, key from KEEP_API_KEY) or streamable-HTTP (remote, each client sends its own X-API-KEY). The sidecar registers the MCP tools/resources via FastMCP and calls keep-backend through KeepClient.

Where it sits in a Keep deployment (opt-in --profile mcp, loopback-only port):

Deployment

Where it sits: keep-mcp is one extra container next to the existing Keep containers in docker-compose.yml. It only starts with --profile mcp, has no database or volume, publishes 8001 on loopback only, and talks only to keep-backend over the compose network. Kubernetes/Helm (keephq/helm-charts) is not covered by this PR.

ELI5

Keep is a big notebook where all the "something is broken!" alarms get written down. AI assistants are smart, but they can't open that notebook on their own.

keep-mcp is a librarian standing next to the notebook. The AI asks a question ("which alarms are ringing?", "tell me about incident 42"), the librarian looks it up in Keep, and hands back the answer so the AI can help a person figure out what went wrong.

House rules:

• Everyone brings their own library card (X-API-KEY). The librarian has no master key, so you only see what Keep already lets you see.
• Read-only by default. It can't change anything unless someone flips the switch (KEEP_MCP_ENABLE_WRITES=true), and every change is written in a logbook.
• Practice before doing. run_workflow shows what it would do (dry_run=true) unless told otherwise.
• Only talks to people in the same room (loopback) unless you deliberately invite others.

What's included

Area	Details
Read tools	search_alerts, list_incidents, get_incident_with_alerts, get_topology, get_alert_history, alert/incident status summaries, workflows (list_workflows, get_workflow, list_workflow_runs, get_workflow_run, get_alert_workflow_executions)
Resources / prompt	keep://topology, keep://incidents/{id}, keep://alerts/{fingerprint}; prompt triage_alert
Write tools (opt-in)	change_incident_status, add_alert_note, run_workflow — only registered with KEEP_MCP_ENABLE_WRITES=true; audit-logged; run_workflow defaults to dry_run=true
Health	/healthz, /readyz (HTTP transport)
Packaging	docker/Dockerfile.mcp (non-root), opt-in mcp profile in docker-compose.yml (published on 127.0.0.1:8001 only)

Security hardening

• Per-request X-API-KEY for tools and resources; no env-key fallback in HTTP mode (key is required).
• Path IDs are percent-encoded (./.. rejected) to prevent path/parameter injection; status filters use fixed allowlists.
• Host/Origin allowlist (DNS-rebinding protection); redirects are never followed (no key leakage); sanitized /readyz; audit log uses %r and a hashed key id.
• Reviewed with an independent security review and CodeRabbit; findings addressed.

Known limitations

• search_alerts / get_alert_status_summary call POST /alerts/query, which triggers Keep's background provider pull (documented in the README).
• The compose keep-backend runs with AUTH_TYPE=NO_AUTH; do not expose the MCP port beyond loopback unless the backend enforces auth.
• Out of scope: LGTM (Loki/Mimir/Tempo/Grafana) passthrough — needs a backend endpoint.

✅ Checks

• My pull request adheres to the code style of this project (black + isort)
• My code requires changes to the documentation (keep-mcp/README.md)
• I have added tests to cover my changes
• All new and existing tests passed (cd keep-mcp && pytest → 25 passed)

ℹ Additional Information

Run locally: cd keep-mcp && pip install -e ".[dev]" && pytest, then KEEP_API_URL=... KEEP_API_KEY=... keep-mcp (stdio) or MCP_TRANSPORT=streamable-http keep-mcp. Docker: docker compose --profile mcp up keep-mcp. Not verified against a live keep-backend or a built Docker image.