Update MCP setup guide with OAuth

docs/cloud/mcp/setup-guide.mdx

@@ -4,92 +4,130 @@ sidebarTitle: "MCP setup guide"
 badge: "Elementary Cloud"
 ---
 
+This guide walks you through connecting any MCP-compatible client (Cursor, Claude Desktop, and others) to Elementary's remote MCP server.
 
-This document walks you through connecting any MCP‑compatible client (Cursor, Claude Desktop, and others) to **Elementary’s production remote MCP server**. 
-It covers prerequisites, installation of the `mcp-remote` helper, authentication, and per‑client configuration steps.
-
-## Prerequisites
-| Requirement | Why it’s needed |
-|-------------|-----------------|
-| **Node.js 18 LTS or newer** | `mcp-remote` (and many editors) run on Node. Verify wit `node --version`. |
-| **npm / npx** | `npx` fetches `mcp-remote` on demand. Bundled with Node. |
-
-> **Recommended:** If you don't have Node.js installed, we recommend using `nvm` (Node Version Manager) for easy installation and management:
-> ```bash
-> # Install nvm (if not already installed)
-> curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-> # Restart your terminal or run: source ~/.bashrc
-> 
-> # Install and use the latest LTS version
-> nvm install --lts
-> nvm use --lts
-> ```
+The server is available at:
 
----
+```
+https://prod.api.elementary-data.com/mcp/
+```
 
-## 1 – Generate an access token
-You can now generate tokens directly from the Elementary UI: go to [User → Personal Tokens](https://app.elementary-data.com/settings/user-tokens) or [Account → Account Tokens](https://app.elementary-data.com/settings/account-tokens).
+## Authentication
 
-Quick steps:
-1. Open the **User → Personal Tokens** or **Account → Account Tokens** page and click **Generate token**.
-2. (Optional) Add a name/description.
-3. Copy the token and store it securely — it is shown once. Manage (revoke/rotate) anytime from the same page.
+<Tabs>
+  <Tab title="OAuth 2.1 (recommended)">
+    Elementary's MCP server supports the **Streamable HTTP** transport with **OAuth 2.1** and dynamic client registration.
 
-### Security
-User tokens are **user‑scoped bearer tokens** and inherit your workspace permissions.
-Account tokens are **account‑scoped bearer tokens** and have "Can View" permissions.
-Treat them like passwords — do not share or commit them. Keep them secret, rotate regularly, and revoke immediately if compromised.
+    When you start the MCP server for the first time, your client opens a browser window so you can log in with your Elementary account. The MCP server uses your authenticated user's permissions directly (user-scoped).
 
+    Use the following config in the client setup steps below:
 
----
+    ```json filename="mcp.json"
+    {
+      "mcpServers": {
+        "Elementary": {
+          "url": "https://prod.api.elementary-data.com/mcp/"
+        }
+      }
+    }
+    ```
 
-## 2 – Install `mcp-remote` (optional)
-You don't have to install anything globally, our configs use npx to fetch the latest version automatically. If you do prefer a global install, use:
-```bash
-# Optional: global install
-npm install -g mcp-remote@latest
-```
+    <Note>
+    Re-authentication is only required when your session expires or you explicitly sign out.
+    </Note>
+  </Tab>
 
-> **Important:** `mcp-remote` expects the **server URL as the first argument** (flags come **after** the URL). It does **not** implement `--help`; running `mcp-remote --help` will error because `--help` is treated as a URL.
+  <Tab title="Access token">
+    Use this method for headless setups, CI environments, or any client that doesn't support browser-based OAuth.
 
----
+    #### Prerequisites
 
-## 3 – Configure your client
-Most MCP‑compatible clients read a JSON config that defines mcpServers. Use one of the following patterns.
-```jsonc
-{
-  "mcpServers": {
-    "elementary-remote": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "mcp-remote@latest",
-        "https://prod.api.elementary-data.com/mcp/",
-        "--header",
-        "Authorization:${AUTH_HEADER}"
-      ],
-      "env": {
-        "AUTH_HEADER": "Bearer <AUTH_TOKEN>"
-      }
-    }
-  }
-}
-```
-**Why the `-y` flag?**  
-It makes `npx` skip the interactive “install this package?” prompt.
+    | Requirement | Why it's needed |
+    |-------------|-----------------|
+    | **Node.js 18 LTS or newer** | `mcp-remote` runs on Node. Verify with `node --version`. |
+    | **npm / npx** | `npx` fetches `mcp-remote` on demand. Bundled with Node. |
+
+    <Tip>
+    If you don't have Node.js installed, use [nvm](https://github.com/nvm-sh/nvm) for easy installation:
 
-### Client‑specific steps
+    ```bash
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+    # Restart your terminal, then:
+    nvm install --lts && nvm use --lts
+    ```
+    </Tip>
 
-#### 3.1 Cursor IDE
-1. **Settings → Model Context Protocol → Add Custom Server**  
-   or edit `~/.cursor/mcp.json` (global) / `<project>/.cursor/mcp.json` (workspace).
-2. Paste the JSON above.
-3. Save – Cursor auto‑restarts its MCP agent.
+    #### Generate an access token
 
-#### 3.2 Claude Desktop
-1. In the menu bar choose **Claude → Settings -> Developer**.
-2. Under **Local MCP Servers**, click **Edit**.
-3. Paste the JSON block
-4. Restart Claude
+    Go to [User → Personal Tokens](https://app.elementary-data.com/settings/user-tokens) or [Account → Account Tokens](https://app.elementary-data.com/settings/account-tokens) and click **Generate token**. Copy the token and store it securely — it is shown only once.
 
+    - **Personal tokens** are user-scoped and inherit your workspace permissions.
+    - **Account tokens** are account-scoped with "Can View" permissions.
+
+    Treat tokens like passwords: do not share or commit them, rotate regularly, and revoke immediately if compromised.
+
+    #### Install `mcp-remote` (optional)
+
+    Our configs use `npx` to fetch `mcp-remote` automatically — no global install required. If you prefer a global install:
+
+    ```bash
+    npm install -g mcp-remote@latest
+    ```
+
+    Use the following config in the client setup steps below:
+
+    ```jsonc filename="mcp.json"
+    {
+      "mcpServers": {
+        "elementary-remote": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "mcp-remote@latest",
+            "https://prod.api.elementary-data.com/mcp/",
+            "--header",
+            "Authorization:${AUTH_HEADER}"
+          ],
+          "env": {
+            "AUTH_HEADER": "Bearer <AUTH_TOKEN>"
+          }
+        }
+      }
+    }
+    ```
+
+    Replace `<AUTH_TOKEN>` with the token you generated above.
+  </Tab>
+</Tabs>
+
+---
 
+## Configure your client
+
+### Cursor IDE
+
+<Steps>
+  <Step title="Open MCP settings">
+    Go to **Settings → Model Context Protocol → Add Custom Server**, or edit `~/.cursor/mcp.json` (global) / `<project>/.cursor/mcp.json` (workspace).
+  </Step>
+  <Step title="Add the server">
+    Paste the JSON block from the authentication tab above and save. Cursor restarts its MCP agent automatically.
+  </Step>
+  <Step title="Authenticate">
+    If using OAuth, a browser window opens on first launch. Log in with your Elementary account to complete authentication.
+  </Step>
+</Steps>
+
+### Claude Desktop
+
+<Steps>
+  <Step title="Open Developer settings">
+    In the menu bar, choose **Claude → Settings → Developer** and click **Edit** under **Local MCP Servers**.
+  </Step>
+  <Step title="Add the server">
+    Paste the JSON block from the authentication tab above and save.
+  </Step>
+  <Step title="Restart Claude">
+    Quit and reopen Claude Desktop. If using OAuth, a browser window opens on first launch for authentication.
+  </Step>
+</Steps>