MCP Server Integration

The Causely MCP server gives agents and AI assistants direct access to Causely's causal reasoning engine. 45 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 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	HTTP	.mcp.json (mcpServers)
Claude Desktop	stdio via mcp-remote	claude_desktop_config.json (mcpServers)
Codex	HTTP	config.toml (mcp_servers)
Cursor	HTTP	.cursor/mcp.json (mcpServers)
VS Code (GitHub 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 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

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.
Tenant-wide API token	A team or shared agent that should not be bound to one person's identity. Create one at 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 and Claude Desktop.

For encoding, headers, and the stdio/mcp-remote fallback, see Advanced Authentication.

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 causal graph
Structured output	Custom parsing required	Typed tool responses
Time to insight	Minutes of analysis	Single tool call

Full Tool Reference

45 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
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
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 model 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 causal model; 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
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)

Feature Demos

Solving Slow Database Queries

Helm Chart Example