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
• Claude Code installed

Configuration

Run once to register Causely across all your projects:

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.

Team-shared config (optional)

To register Causely for everyone who clones a specific repo, create .mcp.json at the repository root instead:

{
  "mcpServers": {
    "causely": {
      "type": "http",
      "url": "https://api.causely.app/mcp"
    }
  }
}

Only use this if authentication is handled separately, never commit credentials. See Advanced Authentication.

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	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	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, then add the header:

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 for the full list, trigger phrases, and override options.

Install

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.