Skip to main content

HolmesGPT

Using Causely with HolmesGPT​

HolmesGPT is a pre-built agent framework for incident investigation and response. When configured with Causely, Holmes gains a live causal model of your system, so it can reason about root cause, blast radius, and remediation without requiring prompt engineering or custom context.

Out of the box, Holmes can access telemetry sources such as metrics and logs. However, like most agents, it operates on raw data and correlation. This makes it difficult to consistently determine what is actually happening, what caused it, and what action is safe.

Causely provides the system intelligence layer that allows Holmes to move from querying telemetry to making reliable, system-aware decisions.

How Causely Enhances Holmes​

When integrated with Holmes, Causely enables:

  • Deterministic root cause analysis: identify the actual source of an issue, not just correlated signals
  • Dependency-aware reasoning: understand how failures propagate across services
  • Structured outputs: return machine-consumable results instead of raw telemetry
  • Explainable decisions: provide clear reasoning that can be audited and trusted

This allows Holmes to focus on orchestrating workflows while relying on Causely for system-level understanding.

Example Workflow​

Scenario: Investigating a performance issue

  1. Holmes receives an alert or user query
  2. Holmes queries Causely via MCP
  3. Causely returns:
    • Root cause service
    • Affected dependencies
    • Explanation of the issue
  4. Holmes:
    • Summarizes the issue
    • Notifies the appropriate team
    • Suggests or executes remediation

Setup​

To integrate Causely with HolmesGPT, configure Causely as a remote MCP server.

Holmes Configuration​

Add the following to your Holmes configuration:

mcp_servers:
  causely:
    description: "Causal Reasoning Platform"
    config:
      url: "https://api.causely.app/mcp"
      mode: streamable-http
      headers:
        Authorization: "Basic {{ env.CAUSELY_MCP_CLIENT_BASIC }}"
    llm_instructions: "Use Causely to investigate application performance issues, analyze distributed traces, and query infrastructure metrics. Prefer this over Prometheus for APM data."

Authentication​

Holmes calls the MCP server non-interactively, so use HTTP Basic with your Causely MCP OAuth client ID and client secret (machine credentials), not a Bearer API key.

  1. In API tokens, create or copy the client ID and client secret for MCP access.
  2. Build the standard Basic user-info string: client_id, a single colon (:), then client_secret, with no newline or extra characters (same encoding as Authorization: Basic elsewhere).
  3. Base64-encode that string. Use the raw Base64 output only in the environment variable; the Holmes snippet above adds the Basic prefix in the header value.

Example (macOS or Linux):

export CAUSELY_MCP_CLIENT_BASIC="$(printf '%s' 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)"

If your stack cannot put those credentials on Authorization, you can send the same payload on X-Causely-Client-Basic instead; see Authentication on the MCP Server page for the full header table and edge cases.

When to Use This Integration​

This integration is most valuable when:

  • You are using Holmes for incident investigation or automation
  • You have distributed systems with complex dependencies
  • You want consistent, reliable root cause analysis instead of correlation
  • You are looking to automate decision-making, not just data retrieval

Notes​

  • Causely complements existing telemetry sources such as Prometheus rather than replacing them
  • Holmes can continue to use other data sources, but should prioritize Causely for system-level reasoning
  • For full details on available tools and key workflows, see the MCP Server documentation

Next Steps​