npm package: @rootcause/rootcause-mcp
Description: Connect Claude Desktop (and other stdio MCP clients) to the RootCause MCP server
Latest version: 0.1.3

# rootcause-mcp

![RootCause causal discovery](https://rootcause.ai/img/platform/causal-discovery.png)

## About RootCause

[RootCause](https://rootcause.ai) is a causal AI platform: you bring your data, define or discover causal structure, and run what‑if analyses and simulations. Build digital twins, explore causal graphs, and query outcomes via the UI or the [Model Context Protocol](https://modelcontextprotocol.io). Full docs: [docs.rootcause.ai](https://docs.rootcause.ai).

This package connects **Claude Desktop**, **Cursor**, and other stdio-based MCP clients to the RootCause platform so you can interact with your causal models from chat.

## How it works

Claude Desktop and Cursor can only talk to MCP servers via **stdio** (spawning a local process). The RootCause MCP server lives remotely at `platform.rootcause.ai/api/v1/mcp`. This package is a thin **stdio-to-SSE bridge** that:

1. Reads your `ROOTCAUSE_API_KEY` from the environment
2. Constructs an `Authorization: Bearer` header
3. Spawns [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to handle the stdio ↔ HTTP/SSE protocol translation
4. Pipes stdio in/out back to the MCP client

`mcp-remote` does the heavy lifting; this package configures it with the right URL and auth header.

## What you can do

Once connected, your AI assistant has full access to your RootCause workspaces. The MCP server exposes tools and resources for:

| Capability | Examples |
|---|---|
| **Workspaces** | List workspaces, get workspace overviews with datasets/models/twins |
| **Datasets** | Browse datasets, inspect schemas and metadata |
| **Data Views** | Query and explore transformed data views |
| **Ontology** | Read ontology concepts, field mappings, and causal relationships |
| **Digital Twins** | List twins, inspect structure, run what-if simulations |
| **Causal Discovery** | Discover causal graphs from data, explore relationships |
| **Interventions** | Run what-if analyses - "what happens if X increases by 10%?" |

### Example conversations

Try asking your assistant:

- *"List my workspaces"*
- *"Show me the datasets in [workspace name]"*
- *"What causal relationships exist between temperature and yield?"*
- *"Run a what-if analysis: what happens to revenue if marketing spend increases by 20%?"*
- *"Describe the digital twin for [model name] and its current status"*

## Requirements

- Node.js 20+
- A RootCause API key - create one at **Settings → API** in the RootCause platform

## Auth scoping

API keys can be **org-wide** or **workspace-scoped**:

- **Org-wide keys** can access all workspaces your account has access to. Recommended for MCP so the assistant can list and switch between workspaces.
- **Workspace-scoped keys** are restricted to a single workspace. Use these when you want to limit access.

## Quick setup

Package on npm: **`@rootcause/rootcause-mcp`** - no global install needed, just use `npx`.

### Claude Desktop

1. **Get your API key** from RootCause (**Settings → API** in the platform).

2. **Open your Claude Desktop MCP config:**
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

3. **Add the RootCause server** - either via the UI or by editing the JSON directly:

#### Option A: Config UI

- **Command:** `npx`
- **Args:** `@rootcause/rootcause-mcp`
- **Env:** `ROOTCAUSE_API_KEY` = your API key (e.g. `pk_...`)

#### Option B: Edit config JSON

```json
{
  "mcpServers": {
    "rootcause": {
      "command": "npx",
      "args": ["@rootcause/rootcause-mcp"],
      "env": {
        "ROOTCAUSE_API_KEY": "pk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

4. **Restart Claude Desktop.** You should see the RootCause server available (hammer icon in the input area).

### Cursor

1. Open **Settings → MCP** in Cursor.
2. Add a new **stdio** server with this command:

```
npx @rootcause/rootcause-mcp
```

3. Set the environment variable `ROOTCAUSE_API_KEY` to your API key.

Alternatively, add to your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rootcause": {
      "command": "npx",
      "args": ["@rootcause/rootcause-mcp"],
      "env": {
        "ROOTCAUSE_API_KEY": "pk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ROOTCAUSE_API_KEY` | Yes | - | RootCause API key (e.g. `pk_...`). |
| `ROOTCAUSE_MCP_URL` | No | `https://platform.rootcause.ai/api/v1/mcp` | MCP server URL. Override for local development (e.g. `http://localhost:3000/api/v1/mcp`). |

## Troubleshooting

- **"ROOTCAUSE_API_KEY is required"** - Set `ROOTCAUSE_API_KEY` in the MCP server's `env` block in your client config.
- **Connection errors** - Check that `ROOTCAUSE_MCP_URL` is reachable and your API key is valid. Verify the key has access to the org/workspace you expect.
- **Windows: command not found or bad path** - Use `npx` as the command and `@rootcause/rootcause-mcp` as the only arg. Do not use the full path to `npx.cmd` or Node.
- **Linux/macOS: EACCES permission errors on global install** - Use `npx` directly (no global install needed). If you must install globally, see [npm's guide to fixing permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
- **Tools not loading** - Make sure your API key has the required scopes. An org-wide key with broad scopes is recommended for MCP.

## License

MIT