Connecting AI Clients

All connection setup happens on the API page, in the MCP Integration section (see API Access). The page generates the exact commands and config for each client with your platform's real URL filled in; the examples below use the placeholder https://<your-platform-domain>.

Prefer the remote OAuth connection: clients register themselves automatically and you sign in through your browser. No API key to copy or leak.

The MCP Integration section generates the setup for each client with your platform's real URL, here the one-command Claude Code path.

---

OAuth connection (recommended)

The config contains no secrets: authorization happens in your browser, tokens are stored by the client, and access is scoped to what you approve.

Claude Code

1. Open a terminal and run:

   claude mcp add --transport http rootcause https://<your-platform-domain>/api/v1/mcp

2. Type /mcp in the chat panel and authenticate: a browser window opens to sign in and authorize.

3. Approve the connection on the consent screen (see below). The same /mcp dialog also enables, disables, and reconnects servers later.

Cursor

1. Open Cursor Settings → MCP, or add to your project's .cursor/mcp.json.

2. Paste the config:

   {
     "mcpServers": {
       "rootcause": {
         "url": "https://<your-platform-domain>/api/v1/mcp"
       }
     }
   }

3. Cursor prompts you to authenticate: a browser window opens to sign in and authorize.

4. Approve the connection on the consent screen, and the RootCause tools appear in Agent mode.

Claude Desktop

1. Open your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Paste the config. It uses mcp-remote, which bridges Claude to the remote server and runs the OAuth sign-in for you (this requires Node.js, since the bridge runs via npx):

   {
     "mcpServers": {
       "rootcause": {
         "command": "npx",
         "args": ["mcp-remote", "https://<your-platform-domain>/api/v1/mcp"]
       }
     }
   }

3. Restart Claude Desktop. A browser window opens the first time to authorize.

Claude on the web (claude.ai)

Claude on the web speaks remote MCP natively — no bridge, no local config file. The MCP Integration section's Claude Web tab hands you the one thing you need: the connector URL.

The Claude Web tab: no config file at all, just the connector URL to paste into claude.ai.

1. In claude.ai, open Settings → Connectors. Custom connectors require a Pro, Max, Team, or Enterprise plan; on Team and Enterprise an owner can add the connector once for the whole workspace.

2. Click Add custom connector, name it RootCause, and paste the URL:

   https://<your-platform-domain>/api/v1/mcp

3. Click Continue, then Connect next to RootCause in the connectors list: you sign in through your browser and land on the same consent screen as every other client.

4. In a chat, enable the connector from the search and tools menu. Connectors added on the web are also available in the Claude mobile apps.

Adding RootCause as a custom connector on claude.ai: a name, the MCP URL, and Continue.

---

The consent screen

Whichever client you use, the browser sign-in ends on the same consent screen. This is where the connection's reach is decided:

• Organisation: which organisation the assistant may work in.

• Workspace: either All workspaces in organisation (the default, so the assistant can list workspaces and move between them) or a single workspace, which pins the connection to that workspace only.

• Access: the permission scopes being granted, listed by area. The list is fixed by what the client requested; you approve or deny it as a whole. Standard MCP clients request the default bundle: read access to your content plus the Agent scopes, so a fresh connection can explore and query but not change your data or models. See Permissions and Safety for what that means in practice and how to give an assistant write access.

Once you approve, consent is remembered: reconnecting the same client for the same or narrower access does not ask again.

The consent screen: pick the organisation, optionally pin a workspace, and review exactly what the client will be able to reach before allowing access.

---

Managing and revoking connections

Every client you authorize appears in the Connected Apps section of the API page, with the scopes it was granted and when. Revoking a connection deletes the grant and kills its refresh tokens immediately, so the app has to sign in again from scratch; an access token already issued stays valid until it expires, up to 15 minutes. Public MCP clients register themselves automatically and only ever appear here, not under OAuth Apps (that section is for confidential clients you build yourself, see OAuth Apps).

Connected Apps lists every assistant you have authorized, with its granted scopes and a one-click revoke.

---

API key connection (legacy)

The legacy method runs the @rootcause/rootcause-mcp stdio bridge locally, authenticated by a static API key. On the API page, select one of your keys in the MCP Integration section and it generates the connection config for you.

Org-wide keys are recommended for this method, so the assistant can list and switch between workspaces; if the integration only ever needs one workspace, scope the key to it instead. See API Access for creating keys.

A key used for MCP must include the Sources read scope. The MCP connection itself requires it, so a key carrying only other scopes (for example just Digital Twins) is rejected when the client connects, before any tool is listed.

---

Troubleshooting

• The client never opens a browser, or tools are missing after an update: in Claude Code, run /mcp and reconnect the server. In Cursor and Claude Desktop, fully restart the app after any config change. On claude.ai, remove and re-add the connector under Settings → Connectors, and check it is enabled in the chat's search and tools menu.

• Claude Desktop shows the server as failed: the mcp-remote bridge runs via npx, so Node.js must be installed and on your PATH.

• Connection rejected with an API key: check the key carries the Sources read scope, has not expired, and that your IP is on the key's allowlist if one is set.

• Tools you expected are not there: the tool list is filtered to what your grant allows. See Permissions and Safety.