> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/api-access/mcp-integration/mcp-connecting-clients.md).

# Connecting AI Clients

All connection setup happens on the **API** page, in the **MCP Integration** section (see [API Access](/api-and-integrations/api-access.md)). 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.

<figure><img src="https://1662811113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBXg3gZLR0e2Q8SzeQmql%2Fuploads%2Fgit-blob-a1c3c613e511ce87e17a24dbde7cc346e0646895%2Frc-api-mcp-integration.png?alt=media" alt="The MCP Integration section of the API page on the OAuth method with the Claude Code tab selected: three setup steps, a terminal command reading claude mcp add --transport http rootcause followed by the platform MCP URL, and a note that no secrets are stored"><figcaption><p>The MCP Integration section generates the setup for each client with your platform's real URL, here the one-command Claude Code path.</p></figcaption></figure>

***

## 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:

   ```bash
   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:

   ```json
   {
     "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`):

   ```json
   {
     "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.

<figure><img src="https://1662811113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBXg3gZLR0e2Q8SzeQmql%2Fuploads%2Fgit-blob-c65008b1d1066de73901a703428d261df6977c78%2Frc-api-mcp-claude-web.png?alt=media" alt="The MCP Integration section of the API page with the Claude Web tab selected: four setup steps for claude.ai&#x27;s Settings and Connectors page, a Connector URL code block reading the platform MCP URL with a Copy URL button, and a note that no secrets are stored"><figcaption><p>The Claude Web tab: no config file at all, just the connector URL to paste into claude.ai.</p></figcaption></figure>

1. In [claude.ai](https://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.

<figure><img src="https://1662811113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBXg3gZLR0e2Q8SzeQmql%2Fuploads%2Fgit-blob-ddca99fbc7de75abe39051a64593b896c6aded51%2Frc-claude-web-add-connector.png?alt=media" alt="The Add custom connector dialog on claude.ai&#x27;s Connectors settings page, filled in with the name RootCause and the platform MCP URL, with Cancel and Continue buttons and a note that Anthropic does not control which tools developers make available"><figcaption><p>Adding RootCause as a custom connector on claude.ai: a name, the MCP URL, and Continue.</p></figcaption></figure>

***

## 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](/api-and-integrations/api-access/mcp-integration/mcp-permissions-and-safety.md) 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.

<figure><img src="https://1662811113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBXg3gZLR0e2Q8SzeQmql%2Fuploads%2Fgit-blob-432671c5d573139b88bd8acc51c0f3c7514079c0%2Frc-api-mcp-consent-screen.png?alt=media" alt="The RootCause consent screen titled Authorize Claude Code, with an Organisation selector set to Acme Corp, a Workspace selector set to All workspaces in organisation, a list of granted scopes showing read access to Sources, Datasets, Ontology, Digital Twins, Simulations, Catalog, Jobs, and Reports plus Agent read and write, and Deny and Allow access buttons"><figcaption><p>The consent screen: pick the organisation, optionally pin a workspace, and review exactly what the client will be able to reach before allowing access.</p></figcaption></figure>

***

## 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](/api-and-integrations/api-access/oauth-apps.md)).

<figure><img src="https://1662811113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBXg3gZLR0e2Q8SzeQmql%2Fuploads%2Fgit-blob-6f8ce4e507f957a400d7d78a3cca0a628920d305%2Frc-api-connected-apps.png?alt=media" alt="The Connected Apps section of the API page expanded, listing one connection named Claude Code marked as Registered itself, with granted scope pills for catalog, jobs, agent, and read access to data, datasets, ontology, digital twins, simulations, and reports, an authorization date, a revoke button, and a warning that revoking stops new access straight away but an already issued access token stays valid for up to 15 minutes"><figcaption><p>Connected Apps lists every assistant you have authorized, with its granted scopes and a one-click revoke.</p></figcaption></figure>

***

## API key connection (legacy)

The legacy method runs the [`@rootcause/rootcause-mcp`](https://www.npmjs.com/package/@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](/api-and-integrations/api-access.md) for creating keys.

{% hint style="warning" %}
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.
{% endhint %}

***

## 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](/api-and-integrations/api-access/mcp-integration/mcp-permissions-and-safety.md).