# Causely documentation: agent-integration > Full content of the "agent-integration" section of the Causely documentation. This file contains all documentation content in a single document following the llmstxt.org standard. ## Custom Agents ### Building Custom Agents with Causely Most custom agents can access telemetry, but struggle to determine what is actually happening, what caused it, and what action is safe. Causely provides the system intelligence layer needed to interpret telemetry consistently and make reliable decisions. Whether you are building internal incident tooling, AI-driven workflows, or automation pipelines, Causely provides the structured system intelligence needed to interpret telemetry and act safely. ### When to Build a Custom Agent Building a custom agent is the right approach when: - You have internal workflows that do not map to existing tools - You want to integrate reliability decisions into your own systems - You are building end-to-end automation (detection → diagnosis → action) - You need full control over logic, policies, and execution ### How It Works Custom agents use Causely to move from raw telemetry to structured, system-aware decisions. Custom agents typically interact with Causely in one of two ways: #### 1. MCP Server (Recommended) Use the Causely MCP Server to provide a standardized interface for agents. Your agent: 1. Receives a signal (alert, event, user input, or a [Causely webhook notification](/workflows/background-agents)) 2. Queries Causely via MCP 3. Receives structured outputs (issues, diagnoses, dependencies, explanation) 4. Takes action based on those outputs This is the fastest way to integrate Causely into agent-based systems. #### 2. API Integration For more control or non-MCP environments, you can interact directly with the Causely API. Your system: 1. Sends queries to Causely (for example, root cause, topology, health) 2. Receives structured, machine-consumable responses 3. Uses those responses to drive logic and actions ### Tool Ordering: Resolve Entities First :::tip **Always call `get_entities()` before querying metrics, SLOs, topology, symptoms, or slow queries.** Most structured tools require an entity ID. `get_entities()` resolves a service or database name to its ID and returns current health status, type, and labels. ::: ### Tool Selection Choose the right tool based on what your agent needs to do with the result. | Use case | Tool | |---|---| | "What's wrong with checkout?" (narrative) | `get_service_summary` | | Issue data for automated routing | `get_issues` | | Metrics for regression detection | `get_metrics` | | Entity ID resolution | `get_entities` | | SLO status with burn rate | `get_slo` | | Blast radius mapping | `get_topology` | | Post-deploy regression check | `reliability_delta` | See the [full tool reference](/agent-integration/mcp-server#full-tool-reference) for all 46 tools. ### Workflow Example: Incident Triage Workflow This example shows a custom agent performing full incident triage using structured MCP tools. **Scenario**: An alert fires. The agent needs to identify the root cause, understand impact, and route to the correct team. ```python # Step 1: Resolve the alerted service name to an entity ID entity = mcp.call("get_entities", query="checkout-service", entity_types=["Service"]) # Returns: entity ID, current health status, type, and labels # Step 2: Get issues and diagnoses for the affected service issues = mcp.call("get_issues", impacted_service_ids=[entity[0]["id"]]) # Returns: Issues with severity, diagnoses, impacted services, and remediation guidance # Step 3: Map the blast radius for the highest-severity issue topology = mcp.call( "get_topology", entity_id=issues[0]["entity_id"], mode="dependents" ) # Returns: upstream services affected by this entity's degradation # Step 4: Route to the correct team and generate a ticket ticket = mcp.call( "generate_ticket", task=f"Investigate issue: {issues[0]['name']}" ) ``` After the incident resolves: ```python # Generate postmortem documentation postmortem = mcp.call("postmortem", issue_id=issues[0]["id"]) # Returns: structured markdown with timeline, blast radius, contributing factors, action items ``` ### What Your Agent Gets from Causely When integrated, your agent can: - Identify the true root cause of issues - Understand service dependencies and failure propagation - Evaluate blast radius before taking action - Work with structured, consistent outputs - Provide explainable decisions This allows your agent to move beyond querying data to making reliable decisions. ### Design Considerations When building custom agents with Causely: - **Trust boundaries**: define what actions can be automated vs require approval - **Policy enforcement**: gate actions based on risk or impact - **Observability**: log decisions and reasoning for auditability - **Fallbacks**: handle cases where no clear diagnosis is identified ### Next Steps - [Using the MCP Server](/agent-integration/mcp-server): full tool reference and key workflows - [Trigger Background Agents](/workflows/background-agents): have Causely push each Issue to your agent through a webhook - [HolmesGPT](/agent-integration/holmes-gpt): see a reference implementation - [API](../../api): explore direct API integration --- ## HolmesGPT ### Using Causely with HolmesGPT HolmesGPT is a pre-built agent framework for incident investigation and response. When configured with Causely, Holmes gains Causely's causal reasoning over a live causality graph 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: ```yaml 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](https://auth.causely.app/oauth/portal/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](/agent-integration/mcp-server#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](/agent-integration/mcp-server) ### Next Steps - [Using the MCP Server](/agent-integration/mcp-server): full tool reference, key workflows, and tool selection guide - [Custom Agents](/agent-integration/custom-agents): build your own workflows using Causely --- ## Advanced Authentication The default browser-based OAuth flow covers most interactive setups. Use this page when you need **credentials that skip the browser** (personal tokens or tenant-wide API tokens), or when your client **only supports stdio**. If you are connecting **Claude Code**, start with `claude mcp add` on the [Claude Code](/agent-integration/mcp-server/claude-code) page. Custom **Claude.ai / Claude Desktop connectors** are a separate path and are not available on every Claude plan. See [Claude Desktop](/agent-integration/mcp-server/claude-desktop). ### Which credential to use {#which-credential} MCP accepts two kinds of client credentials. Both are a `client_id` and `client_secret` that the server exchanges for an access token. What you can query is the same either way; the difference is **who the request runs as**. | Credential | Use when | Identity | Create | |---|---|---|---| | Personal token | You are connecting an agent that should use **your** access | Inherits your user permissions | [Personal tokens](https://auth.causely.app/oauth/portal/personal-tokens) | | Tenant-wide API token | A **team or background agent** should not be bound to one person's identity | Role you assign on the token | [API tokens](https://auth.causely.app/oauth/portal/api-tokens) | **Browser SSO** is the default for Claude Code, Claude Desktop, Cursor, and similar clients. It is convenient for a one-off session, but access tokens expire after a few hours and the client prompts you to sign in again. A personal or tenant-wide token lasts until the expiry you set when you create it. See [API Tokens](/manage/administration/api-tokens) for how to create and rotate tokens. ### Client ID and Client Secret {#authentication} For non-interactive MCP calls, supply client credentials that the server exchanges for a Frontegg access token. The HTTP Basic username is always `client_id` and the password is always `client_secret`. **Encoding** Concatenate `client_id`, a single colon (`:`), and `client_secret`, no newline, no extra characters, then Base64-encode the result: ```bash printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 -w 0 ``` Use the single line of output as the Base64 payload. **How to send it** | Method | When to use | |---|---| | `Authorization: Basic ` | Requests with no `Authorization: Bearer` token, typical for `curl` or custom HTTP clients | | `X-Causely-Client-Basic` | Same Base64 payload (with or without the `Basic ` prefix). Use when an MCP proxy reserves or rewrites `Authorization`. If both headers are present, the server prefers `X-Causely-Client-Basic`. | If the request already includes a non-empty `Authorization: Bearer` token, the server validates that JWT and ignores client credentials entirely. **Adding credentials to a client config** For native HTTP MCP clients, add a `headers` object alongside `url`. Examples for each config format: Claude Code CLI, with a personal or tenant-wide token (no browser prompt): ```bash claude mcp add --scope user --transport http causely https://api.causely.app/mcp \ --header "X-Causely-Client-Basic: Basic ${CAUSELY_MCP_CLIENT_BASIC}" ``` Set `CAUSELY_MCP_CLIENT_BASIC` to the Base64 string without the `Basic ` prefix; the snippet adds the prefix. Omit `--header` to use browser OAuth instead. See [Claude Code](/agent-integration/mcp-server/claude-code). JSON `mcpServers` (Claude Code, Cursor): ```json { "mcpServers": { "causely": { "type": "http", "url": "https://api.causely.app/mcp", "headers": { "X-Causely-Client-Basic": "Basic " } } } } ``` JSON `servers` (VS Code / GitHub Copilot): ```json { "servers": { "causely": { "type": "http", "url": "https://api.causely.app/mcp", "headers": { "X-Causely-Client-Basic": "Basic " } } } } ``` TOML (Codex), use `env_http_headers` to read the value from an environment variable at runtime so secrets stay out of the file: ```toml [mcp_servers.causely] url = "https://api.causely.app/mcp" enabled = true [mcp_servers.causely.env_http_headers] "X-Causely-Client-Basic" = "CAUSELY_MCP_CLIENT_BASIC" ``` Export `CAUSELY_MCP_CLIENT_BASIC` to the Base64 string (without a `Basic ` prefix, Codex does not prepend it for you unless you include it in the variable value). :::caution Do not commit real secrets to source control. Use your tool's secret or input-variable mechanism where available, for example VS Code MCP **`inputs`** and `${input:…}` in `headers`. ::: ### Stdio Fallback (mcp-remote) {#stdio-fallback-mcp-remote} If your client cannot use streamable HTTP to `https://api.causely.app/mcp`, run [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local stdio bridge: your tool launches Node locally; `mcp-remote` handles OAuth and forwards MCP traffic over HTTP to Causely. Requires **Node.js** and `npx` on your PATH. **Browser OAuth (default for this path):** ```json { "mcpServers": { "causely": { "command": "npx", "args": ["mcp-remote", "https://api.causely.app/mcp/"] } } } ``` **Machine credentials:** `mcp-remote` accepts repeated `--header "Name: value"` flags and expands `${ENV_VAR}` inside header values: ```json { "mcpServers": { "causely": { "command": "npx", "args": [ "mcp-remote", "https://api.causely.app/mcp/", "--header", "X-Causely-Client-Basic: Basic ${CAUSELY_MCP_CLIENT_BASIC}" ] } } } ``` Set `CAUSELY_MCP_CLIENT_BASIC` to the Base64 string without the `Basic ` prefix, the snippet above adds the prefix in the header string. --- ## Claude Code Connect Causely to Claude Code to run incident triage, service health checks, and reliability reports without leaving the terminal. ### Prerequisites - Active [Causely account](https://portal.causely.app/) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed ### Configuration Run once to register Causely across all your projects: ```bash claude mcp add --scope user --transport http causely https://api.causely.app/mcp ``` This writes to `~/.claude.json` automatically. No file editing required. Custom Claude.ai connectors are **not** required for this path, and they are not available on every Claude plan. On first connect, Claude Code opens a browser window for Causely SSO. That is fine for a short interactive session. SSO access tokens expire after a few hours, so prefer a **personal token** for daily CLI use, or a **tenant-wide API token** for a team or background agent. See [Authentication](#authentication). **Team-shared config (optional)** To register Causely for everyone who clones a specific repo, create `.mcp.json` at the repository root instead: ```json { "mcpServers": { "causely": { "type": "http", "url": "https://api.causely.app/mcp" } } } ``` Only use this if authentication is handled separately, never commit credentials. See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth). Begin a new Claude Code session (`claude`) after any config change. Run `/mcp` to confirm causely appears as a connected server. ### Authentication | Method | Use when | |---|---| | Browser SSO (default) | One-off interactive session. Claude Code opens a browser on first connect. | | [Personal token](https://auth.causely.app/oauth/portal/personal-tokens) | Daily CLI use, or a background agent that should run as **you**. Inherits your permissions. Lasts until the expiry you set. | | [Tenant-wide API token](https://auth.causely.app/oauth/portal/api-tokens) | A **team or shared agent** that should not be bound to your identity. Same MCP usage; different identity and role. | To skip the browser, encode the token's `client_id` and `client_secret` as described in [Advanced Authentication](/agent-integration/mcp-server/advanced-auth), then add the header: ```bash claude mcp add --scope user --transport http causely https://api.causely.app/mcp \ --header "X-Causely-Client-Basic: Basic ${CAUSELY_MCP_CLIENT_BASIC}" ``` Set `CAUSELY_MCP_CLIENT_BASIC` to the Base64 string without the `Basic ` prefix; the snippet adds the prefix. ### Adding Skills Seven skills activate automatically once installed: one master router (`causely-mcp`) plus six specialists. See the [Skills page](/agent-integration/mcp-server/skills) for the full list, trigger phrases, and override options. **Install** ```bash git clone https://github.com/causely-oss/causely-client mkdir -p ~/.claude/skills cp -r causely-client/skills/* ~/.claude/skills/ ``` This installs to personal scope (`~/.claude/skills/`) so skills are available across all your projects. To commit skills to a single repo instead, replace `~/.claude/skills/` with `.claude/skills/` in each path above. **Restart** Begin a new Claude Code session (`claude`) after installing. **Verify** Try: *"What's broken right now?"* The `causely-health-reporting` skill should activate. ### Try It Now - *"List my clusters."* - *"Are there any active symptoms right now?"* - *"What services are currently degraded?"* - *"Draft a postmortem for the most recent incident."* ### Known Gotcha Project .mcp.json is committed to source control. Never add credentials directly to this file. Use --scope user when registering Causely so auth stays out of the repository. See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth). --- ## Claude Desktop Ask Causely questions in natural language from the Claude desktop app, no terminal, no code. ### Prerequisites - Active [Causely account](https://portal.causely.app/) - [Claude Desktop](https://claude.ai/download) installed - [Node.js](https://nodejs.org/) on the PATH visible to the app (required for `mcp-remote`) ### Configuration There are a few ways to connect depending on how you use Claude: browser or desktop, and UI or config file. Custom **connectors** in Claude.ai and Claude Desktop require a plan that supports them (Pro / Max, or a Team / Enterprise org that has enabled custom connectors). If that UI is missing, use [Claude Code](/agent-integration/mcp-server/claude-code) instead: ```bash claude mcp add --scope user --transport http causely https://api.causely.app/mcp ``` Or skip the connector UI and use the **Developer desktop** config below. Browser SSO tokens expire after a few hours; for longer-lived access, use a [personal token](https://auth.causely.app/oauth/portal/personal-tokens) or a [tenant-wide API token](https://auth.causely.app/oauth/portal/api-tokens). See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth). #### Claude.ai (browser) **Pro / Max** 1. Go to claude.ai → Customize → Connectors 2. Click + then Add custom connector 3. Enter a name (for example Causely) and the server URL: https://api.causely.app/mcp 4. Click Add 5. Sign in to Causely and grant access 6. Return to Claude.ai, the connector is now active **Team / Enterprise** 1. Go to Organization settings → Connectors 2. Click Add → Custom → Web 3. Enter a name (for example Causely) and the server URL: https://api.causely.app/mcp 4. Click Add 5. Team members authenticate individually at Customize → Connectors **Desktop UI** 1. Go to Settings → Connectors 2. Click Customize 3. Click + sign and select Add custom connector 4. Enter a name (for example Causely) and the server URL: https://api.causely.app/mcp 5. Click Add 6. Sign in to Causely and grant access 7. Return to Claude desktop, the connector is now active **Developer desktop app** 1. Go to Settings → Developer 2. Edit Config 3. Edit `claude_desktop_config.json` and merge the `mcpServers` object: ```json { "mcpServers": { "causely": { "command": "npx", "args": ["mcp-remote", "https://api.causely.app/mcp"] } } } ``` Or you can edit the config file directly, **Config file location**: | Platform | Path | |---|---| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | **Restart** Quit and reopen Claude Desktop. On first connect, a browser window opens for Causely OAuth login. After you authorize, Claude Desktop stores the token and reconnects automatically on subsequent launches. ### Adding Skills Seven skills activate automatically once installed: one master router (`causely-mcp`) plus six specialists. See the [Skills page](/agent-integration/mcp-server/skills) for the full list, trigger phrases, and override options. **Install** Ensure that Skills are enabled for your Enterprise or Team plan. 1. Clone the Causely client repo ```bash git clone https://github.com/causely-oss/causely-client cd causely-client/skills ``` 2. Create a .zip file for each sub folder in the skills folder macOS ```bash for dir in causely-mcp causely-postmortem causely-k8s-investigation causely-health-reporting causely-correlated-incidents causely-change-impact causely-alert-triage; do zip -r "${dir}.zip" "$dir" \ --exclude "*/.DS_Store" \ --exclude "__MACOSX/*" \ --exclude "*/.git/*" \ --exclude "*/Thumbs.db" done ``` Windows ```powershell foreach ($dir in @( "causely-postmortem", "causely-mcp", "causely-k8s-investigation", "causely-health-reporting", "causely-correlated-incidents", "causely-change-impact", "causely-alert-triage" )) { $tmp = New-Item -ItemType Directory -Path "$env:TEMP\$dir" Copy-Item -Path $dir\* -Destination $tmp -Recurse -Exclude @('.DS_Store','Thumbs.db') Compress-Archive -Path $tmp -DestinationPath "$dir.zip" -Force Remove-Item $tmp -Recurse -Force } ``` 3. Go to Customize → Skills 4. Click + sign and select Create skill → Upload a skill 5. For each of the 7 `.zip` files: click **+** → **Create skill** → **Upload a skill**, select the file, and save. Repeat until all 7 are uploaded. Each upload creates one skill. **Restart** Quit and reopen Claude Desktop after installing. **Verify** Try: *"What's broken right now?"* The `causely-health-reporting` skill should activate. ### Try It Now - *"List my clusters."* - *"Are there any active symptoms right now?"* - *"What services are currently degraded?"* - *"Draft a postmortem for the most recent incident."* ### Known Gotcha Claude Desktop launches as a GUI app and does not inherit your shell's `PATH`. If `npx` is not found at launch, install Node.js globally, not via `nvm` or a shell-managed version manager, so the binary is visible to the app process. On macOS, the [official Node.js installer](https://nodejs.org/) or `brew install node` is the most reliable approach. --- ## OpenAI Codex Connect Causely to OpenAI Codex to run reliability checks and incident triage alongside your coding workflows. ### Prerequisites - Active [Causely account](https://portal.causely.app/) - [OpenAI Codex](https://openai.com/index/openai-codex/) CLI installed. Update older builds first with `npm i -g @openai/codex`, since remote MCP and skills support landed in recent releases. - For skills: a Codex build with Agent Skills support ### Setup Setup is two steps: connect the MCP server, then add the skills. Step 1 registers the server and signs you in. The skills are a separate install covered in [Step 2: Add the skills](#step-2-add-the-skills), and they are what route your questions to the right tools. ### Step 1: Connect the server Register the Causely MCP server and authenticate: ```bash codex mcp add causely --url https://api.causely.app/mcp codex mcp login causely ``` The first command registers the server. The second opens a browser window for Causely OAuth login. After you authorize, Codex stores the token and refreshes it automatically, no API key to paste. :::note The Codex CLI, IDE extension, and ChatGPT desktop app share one MCP configuration on the same host. Adding the server once makes it available in all three. ::: **Manual alternative** Add the following to `~/.codex/config.toml` or project `.codex/config.toml`: ```toml [mcp_servers.causely] url = "https://api.causely.app/mcp" enabled = true ``` **Config file location** | Scope | Path | |---|---| | User | `~/.codex/config.toml` | | Project | `.codex/config.toml` at the repository root | #### Confirm the connection Run `codex mcp list` to confirm `causely` appears, or type `/mcp` inside a Codex session to view connected servers. Codex reads MCP configuration at launch, so start a new session after any manual edit. ### Step 2: Add the skills Seven skills activate automatically once installed: one master router (`causely-mcp`) plus six specialists. See the [Skills page](/agent-integration/mcp-server/skills/) for the full list, trigger phrases, and override options. Codex reads skills as folders on disk and loads a skill on relevance, or you can invoke one on demand. **Install** Ensure that Skills are enabled for your Enterprise or Team plan. 1. Clone the Causely client repo ```bash git clone https://github.com/causely-oss/causely-client cd causely-client/skills ``` 2. Copy the seven skill folders into a location Codex reads. Pick **one** of the two options below, they differ only in where the skills are available. **Option A, personal.** Installs the skills once for your user account, available in every project. Copies into `~/.codex/skills/`: ```bash mkdir -p ~/.codex/skills cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \ skills/causely-correlated-incidents skills/causely-health-reporting \ skills/causely-k8s-investigation skills/causely-postmortem \ ~/.codex/skills/ ``` **Option B, project.** Installs the skills into a single repository, available only when that repo is open, and shared with anyone who clones it. Commit `.codex/skills/` to version control for team sharing. Replace `` with the path to the repository: ```bash mkdir -p /.codex/skills cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \ skills/causely-correlated-incidents skills/causely-health-reporting \ skills/causely-k8s-investigation skills/causely-postmortem \ /.codex/skills/ ``` :::tip Codex also reads `.claude/skills/` (project) and `~/.claude/skills/` (user). If you already installed the Causely skills for [Claude Code](/agent-integration/mcp-server/claude-code/), Codex picks them up with no extra steps. ::: 3. Start a new Codex session. Skills load at startup. Type `/skills` to browse available skills and confirm the `causely-*` entries appear. **Verify** In a Codex session, try: *"What's broken right now?"* The `causely-health-reporting` skill should activate. **Overrides** Invoke a specific specialist through the `/skills` selector, or name it in natural language: *"use causely-postmortem: write a retrospective for the payment incident on April 25."* To bypass skills entirely, call MCP tools directly. See the [Full Tool Reference](/agent-integration/mcp-server/#full-tool-reference). ### Try It Now - *"List my clusters."* - *"Are there any active symptoms right now?"* - *"What services are currently degraded?"* - *"Draft a postmortem for the most recent incident."* ### Known Gotcha - **Skills load at session start.** Start a new Codex session after adding skills. A running session will not pick them up. - **Sandbox execution.** Codex runs sandboxed by default, so skills that call external scripts or tools may behave differently than in Claude Code, which runs directly in your terminal. The Causely reasoning skills (alert triage, postmortem, correlated incidents) are unaffected. - **Directory name must match the skill `name`.** The folders in the Causely repo already satisfy this. If you rename a folder, its `name` field in `SKILL.md` must match, or the skill fails to load with no error. - **Remote OAuth is build-sensitive.** Native OAuth for remote servers landed in recent Codex releases. If `codex mcp login` fails, update with `npm i -g @openai/codex`, or bridge the OAuth flow with `mcp-remote`: `codex mcp add causely -- npx -y mcp-remote https://api.causely.app/mcp`. - **Machine credentials.** For non-interactive or CI use instead of OAuth, use `env_http_headers` (reads from environment variables at runtime) rather than `http_headers` (static values in the file), to keep secrets out of the config: ```toml [mcp_servers.causely] url = "https://api.causely.app/mcp" enabled = true [mcp_servers.causely.env_http_headers] "X-Causely-Client-Basic" = "CAUSELY_MCP_CLIENT_BASIC" ``` Export `CAUSELY_MCP_CLIENT_BASIC` to the Base64-encoded `client_id:client_secret` string before launching Codex. See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth) for encoding instructions. --- ## Cursor Connect Causely to Cursor to investigate incidents and check service health inline while you code. ### Prerequisites - Active [Causely account](https://portal.causely.app/) - [Cursor](https://www.cursor.com/) with MCP support (1.0+) ### Installation #### Option 1: Cursor plugin (recommended) Install the Causely plugin from [cursor.directory/plugins/causely](https://cursor.directory/plugins/causely) in one click. It configures the MCP server and installs all seven skills automatically, no manual steps required. After installing, open **Settings → MCP** and confirm `causely` appears with a green status indicator. #### Option 2: Manual setup **MCP server** Create or update `.cursor/mcp.json` at the root of your project: ```json { "mcpServers": { "causely": { "type": "http", "url": "https://api.causely.app/mcp" } } } ``` | Scope | Path | |---|---| | User (all projects) | `~/.cursor/mcp.json`, open via **Settings → MCP → Edit Config** | | Project | `.cursor/mcp.json` at the project root | **Add Skills** ```bash git clone https://github.com/causely-oss/causely-client mkdir -p .cursor/skills cp -r causely-client/skills/* .cursor/skills/ ``` Cursor skills are project-scoped; there is no personal skills directory. Run these commands at the root of each project where you want skills available. **Restart** After saving the config, open **Settings → MCP**, `causely` should appear with a green status indicator. If it does not, use **Cmd/Ctrl+Shift+P → MCP: Restart MCP Server** or restart Cursor entirely. **Verify** Try: *"What's broken right now?"* The `causely-health-reporting` skill should activate. ### Try It Now - *"List my clusters."* - *"Are there any active symptoms right now?"* - *"What services are currently degraded?"* - *"Draft a postmortem for the most recent incident."* ### Known Gotcha Cursor caches MCP tool descriptions at session start. If you update the server config or Causely releases new tools, the previous tool list persists until you explicitly restart the MCP server or restart Cursor. See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth) if you need to add machine credentials. --- ## MCP Server Integration The Causely MCP server gives agents and AI assistants direct access to Causely's causal reasoning engine. 46 tools across 6 categories let your agent move from raw alerts to structured root cause analysis, dependency maps, and reliability reports, without writing custom integrations. ### Key Workflows These are the four workflows agents use most often. Each maps to a specific sequence of MCP tool calls. #### Incident Triage Identify the root cause and how far the impact has spread. **Try:** - *"What's broken in production right now?"* - *"Checkout is throwing errors and we have Alertmanager alerts firing. What's the actual root cause?"* - *"Three services are alerting at once. Which is the real problem and which are downstream noise?"* 1. `get_issues()`: list active Issues, the primary incident-level view; drill into one with `get_issue_details(issue_id=...)` 2. `get_symptoms()`: see all active Signals across the entire environment (no filters needed) 3. `get_diagnoses()`: identify all active diagnoses and impacted services 4. `get_alerts(alert_name_filters=...,)`: drill into a specific alert's cause 5. `get_topology(entity_id=..., mode="dependents")`: map which upstream services are affected Handled automatically by `causely-correlated-incidents`, or `causely-alert-triage` if you're starting from a specific alert. #### Quick Service Health Get a complete health picture for a specific service in two calls. **Try:** - *"Is checkout healthy?"* - *"Give me a full health picture for the payments service: status, open issues, SLOs."* - *"Before I page anyone, is there actually a problem with database-service or is this alert noise?"* - *"Are there are any concerning errors or warnings in the logs for the frontend service over the last hour?"* 1. `get_entities(query="service-name", entity_types=["Service"])`: resolve the service name to its entity ID 2. `get_service_summary(service="service-name")`: full snapshot: status, active signals, diagnoses, issues, SLOs, metrics, recent events, error logs 3. `get_logs(entity_id=...,)`: retrieves live log output for a running service Handled automatically by the `causely-health-reporting` skill. #### Post-Deploy Validation Check whether a deployment introduced regressions. **Try:** - *"Did the last deploy to payments cause any regressions?"* - *"We deployed cart service 30 minutes ago. How does it look compared to before?"* - *"Check all services my team owns, did anything degrade after today's deploys?"* 1. `reliability_delta(service="service-name")`: compare CPU, memory, latency, and error rate before vs after the most recent deployment 2. `fleet_reliability_delta(team="team-name")`: batch check across all services for a team, namespace, or explicit list Handled automatically by the `causely-change-impact` skill. #### Post-Incident Reporting Generate postmortem documentation and action items from a resolved incident. **Try:** - *"The payments incident is resolved. Draft a postmortem."* - *"Write up what happened to checkout this morning: timeline, issue, diagnosis, and what was affected."* - *"The payments incident is resolved. Draft the postmortem and create a follow-up ticket for the team."* 1. `get_issue_details(issue_id=...)`: retrieve full diagnosis details, timeline, and blast radius 2. `postmortem(issue_id=...)`: generate a structured postmortem draft 3. `generate_ticket(task="...")`: create a follow-up engineering ticket for Jira, GitHub Issues, or Linear Handled automatically by the `causely-postmortem` skill. ### Skills (Recommended) Skills automate the tool-selection step shown in the workflows above. You describe your situation in natural language; the right specialist activates and runs the correct tool sequence for you. Skills are available for Claude Code, Claude Desktop, and Cursor. | Situation | Skill | Try | |---|---|---| | Incoming alert | `causely-alert-triage` | *"PagerDuty just paged for checkout-latency. What's the actual cause?"* | | Post-deploy validation | `causely-change-impact` | *"Did the last deploy to payments cause any regressions?"* | | Multi-service incident | `causely-correlated-incidents` | *"Three services are alerting at once. What's the real problem?"* | | Health summary / morning standup | `causely-health-reporting` | *"Give me a morning health report for production."* | | Kubernetes investigation | `causely-k8s-investigation` | *"The orders pod keeps OOMKilling. Why?"* | | Postmortem / ticket | `causely-postmortem` | *"Draft a postmortem for the checkout incident that resolved an hour ago."* | See the [Skills page](/agent-integration/mcp-server/skills) for install instructions, full skill detail, and override options. ### Choose Your Client Select your tool for a copy-paste config snippet, config file location, and restart instructions. | Client | Transport | Config format | |---|---|---| | [Claude Code](/agent-integration/mcp-server/claude-code) | HTTP | `.mcp.json` (`mcpServers`) | | [Claude Desktop](/agent-integration/mcp-server/claude-desktop) | stdio via `mcp-remote` | `claude_desktop_config.json` (`mcpServers`) | | [Codex](/agent-integration/mcp-server/codex) | HTTP | `config.toml` (`mcp_servers`) | | [Cursor](/agent-integration/mcp-server/cursor) | HTTP | `.cursor/mcp.json` (`mcpServers`) | | [VS Code (GitHub Copilot)](/agent-integration/mcp-server/vscode-copilot) | HTTP | `.vscode/mcp.json` (`servers`) | **Verify your connection** by asking: *"Causely: What Issues are currently active?"* ### Other MCP-compatible Clients The clients above have dedicated setup pages. The following tools also support the Causely MCP server, point them at `https://api.causely.app/mcp` using your tool's HTTP MCP config. See [Advanced Authentication](/agent-integration/mcp-server/advanced-auth) for credential options. **IDEs and Editors:** JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, GoLand, and others), Windsurf, Zed **CLIs:** Kiro CLI, Amp, Atlassian Rovo DEV CLI, and other MCP-compatible CLI tools **Agent Frameworks:** HolmesGPT ### Authentication {#authentication} The MCP server validates Frontegg-issued Bearer tokens. Pick the path that matches how you run the agent: | Method | Use when | |---|---| | Browser OAuth (SSO) | Interactive Claude Code, Claude Desktop, Cursor, or VS Code. No token to paste. Access tokens expire after a few hours. | | Personal token | Daily CLI use or a background agent that should run as **you**. Create one at [personal tokens](https://auth.causely.app/oauth/portal/personal-tokens). | | Tenant-wide API token | A **team or shared agent** that should not be bound to one person's identity. Create one at [API tokens](https://auth.causely.app/oauth/portal/api-tokens). | Claude Code uses `claude mcp add --scope user --transport http causely https://api.causely.app/mcp`, not Claude.ai connectors. Connectors are optional and are not available on every Claude plan. See [Claude Code](/agent-integration/mcp-server/claude-code) and [Claude Desktop](/agent-integration/mcp-server/claude-desktop). For encoding, headers, and the [stdio/mcp-remote fallback](/agent-integration/mcp-server/advanced-auth#stdio-fallback-mcp-remote), see [Advanced Authentication](/agent-integration/mcp-server/advanced-auth). ### Using the Tool Reference :::tip **The reference below is for teams building custom agents that need explicit tool control.** If you're using Claude, Cursor, Codex, or any conversational agent, you can skim it for capability awareness. In most cases, you can describe what you want and the agent picks the right tools. One thing worth knowing if you do go programmatic: most structured tools require an entity ID, so `get_entities()` is usually the right first call. ::: ### What Agents Get vs Raw Telemetry | | Raw telemetry | Causely MCP | |---|---|---| | Root cause identification | Correlation-based, requires analysis | Deterministic causal analysis | | Dependency awareness | Manual mapping required | Live topology from observed traffic | | Blast radius | Estimated | Computed from the causality graph | | Structured output | Custom parsing required | Typed tool responses | | Time to insight | Minutes of analysis | Single tool call | ### Full Tool Reference 50 tools across 6 categories. All tools are available to any MCP-compatible agent or assistant. Configuration tools require the Developer or Administrator role. #### Entity Resolution | Tool | When to use | |---|---| | `get_entities` | **Start here.** Resolve a service or database name to its ID; list all entities in a namespace; check current health status | | `name_lookup` | Resolve any name, including service, cluster, namespace, issue name, or symptom name, to an entity ID for use in other tools. Matches partial cluster and namespace names (for example, "robot" finds `robot-shop`). Accepts a `service_types` filter to tell apart services that share a name | | `get_label_values` | Enumerate valid label values (team, product, cluster, namespace) before fanning out queries across environments | | `count_entities` | Count entities grouped by cluster, namespace, customer, product, or type to grasp the shape of an environment in far fewer calls, without listing every entity | #### Data Retrieval | Tool | When to use | |---|---| | `get_metrics` | Retrieve numeric metric data (p95 latency, error rate, CPU, memory, throughput): the only tool that returns time-series | | `get_logs` | Inspect live service logs, or retrieve evidence logs captured at diagnosis detection time | | `get_alerts` | Start triage from an alert name (PagerDuty, Slack, Datadog); distinguish alerts mapped to causal analysis from noise | | `get_events` | Correlate symptom onset with deployments, restarts, scaling events, or config changes | | `get_config` | Investigate configuration drift; verify deployment manifest matches expectations | | `get_slow_queries` | Identify database queries consuming the most execution time; follow up on database diagnosis | #### Health & Diagnosis | Tool | When to use | |---|---| | `get_issues` | List active Issues. An Issue groups related diagnoses for an affected entity into one incident with a designated primary diagnosis; start incident investigation at the Issue level | | `get_issue_details` | Full detail for one Issue by ID: the primary diagnosis evidence (causal chain, blast radius) plus every diagnosis grouped under it. Follow-up to `get_issues` | | `get_symptoms` | Call with no filters to see all active symptoms across the entire environment or filter for specific entity, namespace or cluster | | `get_diagnoses` | Identify active diagnoses; filter by impacted service, symptom, diagnosis ID, or a start/end date range; use start/end dates when investigating a specific past time window | | `get_diagnosis_details` | Follow-up to `get_diagnoses`: full evidence for one diagnosis given a `diagnosis_id`; includes the causal chain explaining why it was identified, blast radius, symptoms, exceptions, events, and logs | | `get_entity_health` | Structured health summary for non-Service entities (databases, pods, queues, topics, tables) | | `get_environment_health` | Structured health summary for the environment, can be scoped to specific namespaces or services | | `get_slo` | Check SLO state, error budget remaining, and burn rate | | `get_topology` | Find upstream blast radius (dependents), downstream dependencies, or full data-flow graph | | `get_integration_status` | Verify monitoring coverage; check scraper health by cluster | | `get_incident_impact` | Given a Issue ID (or an entity ID + Issue name), returns the responsible service and its business context, plus all impacted services and their business context | | `get_business_transaction_summary` | Health summary for a business transaction (a critical customer journey such as "checkout") by name; aggregates status, symptoms, metrics, dependency health, and recent events across every route it groups | | `team_health` | Health summary for all services owned by a team; degraded and critical services listed first | | `get_service_summary` | Comprehensive health snapshot for a single service: status, symptoms, diagnoses, SLOs, metrics, events, logs | | `investigate_alert` | Investigate a resolved alert from `get_alerts`; maps the alert to its entity and returns the standard `get_entity_health` result alongside the original alert | | `rank_entities` | Rank services, topics, tables, or endpoints by number of dependencies or dependents, a single bulk query instead of looping `get_topology` | | `get_potential_diagnoses` | Active and model-inferred diagnosis hypotheses for a specific entity; includes inactive and causality-only potentials not returned by `get_diagnoses` | | `get_potential_observable_signals` | All observable signals on a specific entity (active, inactive, and causality potential state); use before `get_signal_potential_diagnoses` to find internal signal names | | `get_signal_potential_diagnoses` | Reverse lookup: given a symptom, event, or SLO on an entity, return the diagnosis from the causality graph that could explain it | | `get_diagnosis_observable_signals` | Retrieve the theoretical causality chain for a diagnosis, including downstream symptoms, events, and SLOs it could cause according to the causality graph; compare to observed signals from `get_symptoms` | #### Configuration Requires the Developer or Administrator role. | Tool | When to use | |---|---| | `create_threshold_configuration` | Set a custom metric threshold for an entity so a Signal stops firing on a value that's normal for that service, or set an SLO's target (`TargetThreshold`) and burn rate threshold (`BurnRate`) | | `get_threshold_configurations` | List existing threshold configurations, optionally filtered by entity | | `update_threshold_configuration` | Modify an existing threshold configuration | | `delete_threshold_configuration` | Remove a threshold configuration and revert the metric to its default threshold | | `get_supported_threshold_metrics` | List which metrics support a custom threshold for a given entity, before calling `create_threshold_configuration` | | `get_service_tier` | Check a service's assigned priority tier | | `set_service_tier` | Set a service's priority tier, or enable SLO tracking on a non-Service entity such as an HTTP path or queue | | `clear_service_tier` | Remove a service's assigned priority tier, reverting it to the default | | `ignore_issue` | Snooze an Issue until a chosen time so it stops surfacing in active views | | `unignore_issue` | Reverse a snooze and restore an Issue to active views immediately | | `get_issue_ignore_status` | Check whether an Issue is currently snoozed and until when | #### Reporting & Postmortems | Tool | When to use | |---|---| | `postmortem` | Generate a deterministic postmortem draft for a resolved incident from Causely data | | `generate_ticket` | Create a structured engineering ticket suitable for Jira, GitHub Issues, or Linear | | `submit_feedback` | Submit thumbs up/down and optional comments after a multi-tool investigation; pass `tools_used` for analytics | #### Reliability & Deployment | Tool | When to use | |---|---| | `reliability_delta` | Post-deploy regression check for a single service: compare resource consumption before/after most recent deployment | | `fleet_reliability_delta` | Batch regression check across a team, namespace, or explicit service list (up to 20 services per call) | | `create_snapshot` | Capture topology, active diagnoses, and resource and service metrics over a window of up to 2 hours. The snapshot is built asynchronously: PENDING, then COMPLETE or FAILED | | `get_snapshots` | List snapshots and check their status | | `compare_snapshots` | Compare two COMPLETE snapshots. Pass the baseline first. Returns an ACCEPTED or REJECTED assessment, entity changes, new and cleared diagnoses, resource metrics, and service metrics | | `delete_snapshot` | Delete a snapshot | Creating and deleting snapshots requires the Developer or Administrator role. For how snapshots work, see [Reliability Delta](/in-action/reliability-delta#using-snapshots-through-mcp). ### Feature Demos #### Solving Slow Database Queries #### Helm Chart Example --- ## Skills Skills eliminate the need to pick the right MCP tool manually. You describe your situation; the `causely-mcp` router picks the matching specialist; the specialist runs the correct tool sequence for you. All 29 MCP tools are covered across 7 skills: one master router plus 6 specialists. ### How it works `causely-mcp` is the master router that sits above the six specialist skills. It activates on any observability or reliability question and matches your prompt against each specialist's trigger set, delegating to the closest fit. The router also pulls in `complete-investigation.md` as a shared reference so specialists can coordinate context across multi-step investigations. You never invoke a specialist directly; the router handles that automatically, though you can [override it](#overrides-and-escape-hatches) when needed. ### Client support | Client | Install | |---|---| | Claude Code | [Manual (copy from repo)](/agent-integration/mcp-server/claude-code) | | Claude Desktop | [Manual (copy from repo)](/agent-integration/mcp-server/claude-desktop) | | Cursor | [Plugin (one-click)](/agent-integration/mcp-server/cursor) or [Manual](/agent-integration/mcp-server/cursor#option-2-manual-setup) | | Codex | [Manual (copy from repo)](/agent-integration/mcp-server/codex) | | VS Code Copilot | [Manual (copy from repo)](/agent-integration/mcp-server/vscode-copilot) | ### causely-alert-triage Activates on any message that names or describes an incoming alert from PagerDuty, Datadog, Prometheus/Alertmanager, Slack, or OpsGenie, or asks what a firing alert means. **Example trigger prompts** - *"PagerDuty is firing P1 for checkout-service. What's the root cause?"* - *"I have three Datadog alerts going off at once. Which one actually matters?"* - *"OpsGenie woke me up at 2 AM for payment-processor. Is this real or noise?"* - *"Alertmanager is showing HighErrorRate on api-gateway. What's actually broken?"* **Under the hood** Calls `get_alerts` to fetch the raw alert payload (supports substring search by alert name with no entity IDs needed), `investigate_alert` as a one-step follow-up to get entity health alongside the alert context, and `get_issues` to surface the confirmed diagnosis cause for mapped alerts.
### causely-change-impact Activates on any message asking whether a recent deployment, rollout, or config change caused a regression or reliability shift. **Example trigger prompts** - *"We deployed v2.3.1 of order-service 20 minutes ago. Did it break anything?"* - *"Reliability got worse right after this morning's rollout. What degraded?"* - *"Compare service health before and after today's deploy to checkout."* - *"Did our canary release introduce any downstream failures?"* **Under the hood** Calls `get_events` to locate the deployment event, `reliability_delta` to compare reliability before and after, `fleet_reliability_delta` for a fleet-wide comparison, `get_incident_impact` to retrieve the responsible service and impacted services with business context once a diagnosis is confirmed, `get_config` to inspect the deployed configuration, and `get_metrics` for specific metric trends.
### causely-correlated-incidents Activates on any message describing multiple services alerting simultaneously, or asking about blast radius, cascading failures, dependency chains, or whether separate incidents share a single cause. **Example trigger prompts** - *"Five services are alerting at the same time. Is there a single root cause?"* - *"Checkout, payments, and inventory all degraded. Is this one incident?"* - *"We have a cascade in production. Where did it start?"* - *"Which services will be affected if database-primary goes down?"* **Under the hood** Calls `get_issues` to find all active Issues and their Diagnoses, `get_topology` to map the dependency graph and blast radius, `get_alerts` to correlate firing alerts across services, and `get_incident_impact` to retrieve the responsible service and blast radius with business context for a confirmed Issue.
### causely-health-reporting Activates on any request for a health summary, SLO status update, standup report, reliability overview spanning multiple services or an entire environment, or a single-service health check ("is X healthy?"). **Example trigger prompts** - *"Give me a standup summary of service health for the platform team."* - *"Which services are closest to breaching their SLOs this week?"* - *"Summarize overnight health of all production services."* - *"What's the reliability snapshot for the checkout domain?"* **Under the hood** Calls `get_environment_health` for an environment-wide summary, `get_service_summary` for per-service detail, `get_slo` for SLO status, `team_health` for team-scoped aggregation, `get_symptoms` for a full signal scan across all entities, and `get_diagnoses` to flag any active issues.
### causely-k8s-investigation Activates on any message about Kubernetes infrastructure health: nodes, pods, namespaces, deployments, DaemonSets, or containers. These include OOMKills, pod restarts, node pressure, scheduling failures, resource exhaustion, CrashLoopBackOff, and evictions. **Example trigger prompts** - *"payment-processor pods keep OOMKilling. What's causing it?"* - *"Why does api-gateway restart every few hours?"* - *"Node pressure is high on cluster west-1. Which workloads are to blame?"* - *"My pods are crash-looping but the logs don't show an obvious error."* **Under the hood** Calls `get_service_summary` for a full service-level health check, `get_environment_health` for namespace sweeps, `get_symptoms` for a pod-level signal scan, `get_incident_impact` to retrieve the responsible service and impacted services with business context for a confirmed issue, `get_entity_health` for pod or node status, `get_events` for recent Kubernetes events (OOMKill, CrashLoopBackOff, evictions), `get_config` to inspect resource requests and limits, `get_metrics` for CPU and memory trends, `get_logs` for container log analysis, and `get_diagnoses` scoped to a namespace.
### causely-postmortem Activates on any request to write a postmortem, incident retrospective, or create a ticket documenting a completed or past incident. **Example trigger prompts** - *"Write a postmortem for yesterday's checkout incident."* - *"Draft a Jira ticket for the payment service incident last night."* - *"Create an incident retrospective for the database brownout on Friday."* - *"Generate an RCA document for the cascade failure in production on April 25."* **Under the hood** Calls `get_diagnoses` to reconstruct the incident timeline, `postmortem` to generate the structured retrospective document, and `generate_ticket` to create a Jira or Linear ticket draft.
### Overrides and escape hatches **Force a specific skill** Prefix your prompt with `use causely-` to bypass the router and invoke a specific specialist directly: ``` use causely-postmortem: write a retrospective for the payment incident on April 25 ``` **Bypass skills entirely** You can call MCP tools directly without involving any skill. See the [Full Tool Reference](/agent-integration/mcp-server#full-tool-reference) for the complete list of tools and parameters. **If the wrong skill activates** Tell the agent which skill to use instead: `use causely-`. If a skill consistently miss routes on a prompt you expect to work, email [support@causely.ai](mailto:support@causely.ai) with the prompt text and which skill activated. --- ## VS Code (GitHub Copilot) Connect Causely to GitHub Copilot in VS Code to query root causes and service health from Copilot Chat. ### Prerequisites - Active [Causely account](https://portal.causely.app/) - [VS Code](https://code.visualstudio.com/) with the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension (version 0.22+ for MCP support) - For skills: a recent VS Code build with Agent Skills support (VS Code 1.108 or later) and Copilot **agent mode** enabled ### Setup Setup is two steps: connect the MCP server, then add the skills. The badge below handles the first step. The skills are a separate install covered in [Step 2: Add the skills](#step-2-add-the-skills), and they are what route your questions to the right tools. ### Step 1: Connect the server Click to install the Causely MCP server in VS Code: [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Causely_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22causely%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//api.causely.app/mcp%22%7D) VS Code opens a confirmation dialog showing the server config. Confirm, and on first connect a browser window opens for Causely OAuth login. After you authorize, VS Code stores the token and reconnects automatically. :::note The badge must be clicked from a browser or the rendered docs page, not from inside VS Code. Clicking a `vscode:` link within VS Code resolves it as a file path and fails. ::: **Manual alternative** Create or update `.vscode/mcp.json` in your workspace: ```json { "servers": { "causely": { "type": "http", "url": "https://api.causely.app/mcp" } } } ``` :::note VS Code Copilot uses `servers` as the top-level key, not `mcpServers`. Using `mcpServers` silently fails, the server simply won't appear. ::: **Config file location** | Scope | Path | |---|---| | Workspace | `.vscode/mcp.json` at the repository root | | User | Command Palette → **MCP: Open User Configuration** | #### Confirm the connection After connecting, open the Command Palette and run **MCP: List Servers** to confirm `causely` appears. Copilot Chat picks up the server on the next conversation turn, no full restart required. ### Step 2: Add the skills Seven skills activate automatically once installed: one master router (`causely-mcp`) plus six specialists. See the [Skills page](/agent-integration/mcp-server/skills/) for the full list, trigger phrases, and override options. VS Code reads skills as folders on disk. Copilot discovers any skill directory in a supported location and loads it on relevance. **Install** Ensure that Skills are enabled for your Enterprise or Team plan. 1. Clone the Causely client repo ```bash git clone https://github.com/causely-oss/causely-client cd causely-client/skills ``` 2. Copy the seven skill folders into a location VS Code reads. Pick **one** of the two options below, they differ only in where the skills are available. **Option A, personal.** Installs the skills once for your user account, available in every workspace. Copies into `~/.copilot/skills/`: ```bash mkdir -p ~/.copilot/skills cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \ skills/causely-correlated-incidents skills/causely-health-reporting \ skills/causely-k8s-investigation skills/causely-postmortem \ ~/.copilot/skills/ ``` **Option B, workspace.** Installs the skills into a single repository, available only when that repo is open, and shared with anyone who clones it. Replace `` with the path to the repository. Copies into `.github/skills/`: ```bash mkdir -p /.github/skills cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \ skills/causely-correlated-incidents skills/causely-health-reporting \ skills/causely-k8s-investigation skills/causely-postmortem \ /.github/skills/ ``` :::tip VS Code also reads `.claude/skills/` (workspace) and `~/.claude/skills/` (user). If you already installed the Causely skills for [Claude Code](/agent-integration/mcp-server/claude-code/), VS Code picks them up with no extra steps. ::: 3. Reload the window: Command Palette → **Developer: Reload Window**. In Copilot Chat, switch to **agent mode**, then type `/` to see the `causely-*` skills listed as slash commands, or run `/skills` to open the Configure Skills menu. **Verify** In Copilot Chat agent mode, try: *"What's broken right now?"* The `causely-health-reporting` skill should activate. To confirm a specific skill loads, invoke it directly with `/causely-health-reporting`. **Overrides** Force a specific specialist with its slash command, for example `/causely-postmortem`, or with natural language: *"use causely-postmortem: write a retrospective for the payment incident on April 25."* To bypass skills entirely, call MCP tools directly. See the [Full Tool Reference](/agent-integration/mcp-server/#full-tool-reference). ### Try It Now - *"List my clusters."* - *"Are there any active symptoms right now?"* - *"What services are currently degraded?"* - *"Draft a postmortem for the most recent incident."* ### Known Gotcha - **Skills load in agent mode only.** In ask or edit mode, the skills are not consulted. Switch Copilot Chat to agent mode before testing. - **Older VS Code builds ignore the skills folders silently.** If `/causely-*` commands do not appear after a reload, confirm your VS Code version supports Agent Skills (1.108 or later) and that the GitHub Copilot extension is current. - **Directory name must match the skill `name`.** The folders in the Causely repo already satisfy this. If you rename a folder, its `name` field in `SKILL.md` must match, or the skill fails to load with no error. - **Enterprise policy.** If your organization uses GitHub Copilot Business or Enterprise, an admin may need to allow MCP servers, and in some cases Agent Skills, in the Copilot policy settings before user-configured skills and servers connect. See [Advanced Authentication](https://docs.causely.ai/agent-integration/mcp-server/advanced-auth/) for adding machine credentials via `headers` or VS Code `inputs`. - **Routing behavior can differ from Claude.** In VS Code, Copilot matches your prompt against each skill's `description` directly, so a specialist may activate without going through the `causely-mcp` router. This is expected. If a prompt consistently routes to the wrong specialist, name the correct one with its slash command and email support@causely.ai with the prompt text. --- ## Agent Integration ### Building Reliable Agents with Causely Agents fail not because they lack data. They fail because data alone does not explain causality. An agent with access to metrics, logs, and traces still cannot reliably determine what caused an issue, how far it has spread, or what action is safe to take. That requires causal knowledge: a structured understanding of how services, dependencies, and failure patterns relate. Causely provides that causal knowledge. Agents query Causely through the MCP server and receive structured, deterministic answers, including issues, diagnoses, blast radius, dependency maps, and remediation guidance, instead of raw signals to interpret. ### The Gap in Today's Agent Architectures Most agent-driven systems run into three core limitations: **Information gap** Agents can retrieve telemetry, but cannot consistently determine what is happening or what matters. **System gap** There is no shared understanding of how services, infrastructure, and dependencies relate to each other. **Execution gap** Agents lack a reliable way to determine which actions are safe and how to coordinate them. As a result, agents require human interpretation, and automation breaks down at scale. :::tip Benchmark: agents with and without Causely Agents using Causely cut token consumption 48%, ran 63% faster, and hit 100% diagnosis accuracy across 72 benchmark experiments. [See the benchmark →](https://causely.ai/product/benchmark) ::: ### Where Causely Fits Causely provides a system intelligence layer that continuously reasons about how your system behaves: its services, dependencies, and failure propagation. Instead of reasoning over raw telemetry, agents interact with structured, deterministic system knowledge. Decisions are based on how the system actually behaves, not on correlation or heuristics. ### Two ways to use Causely **On Demand.** An alert fires, Causely answers why. Route existing alerts into Causely or let your agent query Causely's MCP server as part of an investigation. One call returns whether the alert is real or noise, the diagnosis, blast radius, and supporting evidence. **Proactive.** Causely surfaces emerging system degradation with its diagnosis attached, and triggers a background agent to act. This same payload can be sent to any destination you choose before an SLO is violated or an incident is declared. See [Trigger Background Agents](/workflows/background-agents) to set up the webhook. ### Architecture Overview ``` [Agent (for example Holmes or custom agent)] ↓ [Causely (causal models + causality graph + reasoning)] ↓ [Observability + Infrastructure (metrics, traces, logs, alerts)] ``` - **Agent**: orchestrates workflows, queries systems, and takes action - **Causely**: builds and maintains a live causality graph and provides deterministic reasoning - **Observability + Infrastructure**: provides raw signals and telemetry ### What Your Agent Can Do The Causely MCP server exposes 46 tools across 6 categories. Here is what each category enables: - **Entity Resolution**: Resolve service and database names to IDs, enumerate namespaces and clusters, check current health status. Most workflows start here. - **Data Retrieval**: Retrieve time-series metrics, live logs, alert history, deployment events, configuration files, and slow query analysis for any entity. - **Health & Diagnosis**: Get active symptoms environment-wide, identify root causes with impacted services and remediation guidance, check SLOs, map service topology, and get structured health summaries for services, teams, or individual entities. - **Configuration**: Set custom metric thresholds, service priority tiers, and snooze Issues, without leaving the agent session. Requires the Developer or Administrator role. - **Reporting & Postmortems**: Generate deterministic postmortem drafts and structured engineering tickets from resolved incident data. - **Reliability & Deployment**: Compare resource consumption before and after deployments for a single service or an entire fleet. ### Integration Paths Choose based on how much you want to build. | Option | Best for | What you get | |---|---|---| | [MCP Server](/agent-integration/mcp-server) | Any MCP-compatible agent or assistant | Standardized interface to all 45 Causely tools; works with Cursor, Claude Code, VS Code, and others | | [HolmesGPT](/agent-integration/holmes-gpt) | Teams already using Holmes | Pre-built agent with Causely MCP configured; no custom integration required | | [Custom Agents](/agent-integration/custom-agents) | Teams building internal tooling or automation pipelines | Full control over logic, policies, and execution; MCP or direct API | | [Background Agents](/workflows/background-agents) | Teams running autonomous agents that should start as soon as an Issue is detected | Generic Webhook push of the Issue and its diagnosis; the agent then investigates through MCP | If you are starting fresh, use the MCP Server. It works with any agent that supports the Model Context Protocol and requires no custom code. ### Example Workflow **Scenario: High error rate alert** 1. The agent receives an alert 2. The agent calls `get_entities()` to resolve the alerted service name to an entity ID 3. The agent calls `get_diagnoses()` to identify the source 4. Causely returns: - Root cause service - Affected dependencies - Explanation of why this is the cause - Remediation guidance 5. The agent: - Notifies the correct team - Suggests or executes remediation ### When This Approach Is Most Valuable This architecture is most effective when: - You operate distributed systems where issues propagate across services, infrastructure, and dependencies - You already have observability in place - You are building or evaluating automated incident workflows ### Summary Causely does not replace your agents or your observability stack. It provides the system intelligence layer required for agents to interpret telemetry consistently, identify true root causes, and take safe, coordinated action.