Merge pull request #1978 from elementary-data/mcp-setup-guide

Refine MCP setup guide with clearer instructions and troubleshooting …

Author: MikaKerman

docs/cloud/mcp/setup-guide.mdx

@@ -4,25 +4,30 @@ sidebarTitle: "MCP setup guide"
 ---
 
 
-This document walks you through connecting any MCP‑compatible client (Cursor, Claude Desktop, VS Code, and others) to **Elementary’s production remote MCP server**. It covers prerequisites, installation of the `mcp-remote` helper, authentication, and per‑client configuration steps.
+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 via `npx`, which depends on Node. Verify with `node --version`. |
-| **npm / npx** | Bundled with Node; `npx` fetches `mcp-remote` on demand. |
+| **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. |
+
+> Tip: If you use `nvm`, run `nvm install --lts` and `nvm use --lts`.
+
 ---
 
-## 1 – Install `mcp-remote`
-For one‑off use, you can rely on `npx` to auto‑download the package each time:
-```bash
-npx -y mcp-remote --help
-```
-To avoid first‑run latency (or to pin a version) install globally:
+## 1 – 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
 ```
+
+> **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.
+
 ---
+
 ## 2 – Generate a personal access token
 **Design Partner Stage:** Personal access tokens are currently available to design partners only. To obtain a token, please reach out to the Elementary team and we'll provide you with one manually.
 **Coming soon:** Self-service token management will be available directly from the Elementary UI for all users.
@@ -31,23 +36,48 @@ These tokens inherit **your** workspace permissions:
 * Treat them like passwords – **do not share or commit** them.  
 * Rotate regularly.  
 * Revoke immediately if compromised.
+
 ---
-## 3 – Universal configuration JSON
-Insert the block below into your client’s MCP configuration file, replacing `...` with your token:
+
+## 3 - Validate the connection
+This confirms you can reach the Elementary MCP server.
+> Note: Replace `<AUTH_TOKEN>` with your actual token.
+
+```bash
+npx -y mcp-remote@latest https://prod.api.elementary-data.com/mcp/ \
+  --header "Authorization: Bearer <AUTH_TOKEN>" \
+  --health --debug
+```
+
+Optional deeper check (list tools/resources):
+```bash
+npx -y mcp-remote@latest mcp-remote-client https://prod.api.elementary-data.com/mcp/ \
+  --header "Authorization: Bearer <AUTH_TOKEN>" \
+  --list-tools --debug
+```
+
+**Troubleshooting**
+| Symptom | Remedy |
+|---------|--------|
+| `node: command not found` | Install Node ≥ 18 and ensure it’s on `PATH`. |
+| `401 Unauthorized` | Token expired or pasted incorrectly → regenerate. |
+
+## 4 – 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",                              // auto‑install if missing
-        "mcp-remote",
+        "-y",
+        "mcp-remote@latest",
         "https://prod.api.elementary-data.com/mcp/",
         "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
+        "Authorization:${AUTH_HEADER}"
       ],
       "env": {
-        "AUTH_TOKEN": "..."
+        "AUTH_HEADER": "Bearer <AUTH_TOKEN>"
       }
     }
   }
@@ -56,37 +86,22 @@ Insert the block below into your client’s MCP configuration file, replacing `.
 **Why the `-y` flag?**  
 It makes `npx` skip the interactive “install this package?” prompt.
 
-## 4 – Client‑specific steps
-### 4.1 Cursor IDE
+### Client‑specific steps
+
+#### 4.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.
-### 4.2 Claude Desktop
-1. In the menu bar choose **Claude → Developer Settings** to enable advanced configuration.
-2. Edit `claude_desktop_config.json`  
-   * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  
-   * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-3. Paste the JSON block and **restart Claude**. A hammer icon confirms the server is active.
-### 4.3 Visual Studio Code (GitHub Copilot Chat ≥ v1.102)
-1. **Command Palette → MCP: Open User Configuration**  
-   _or_ create `.vscode/mcp.json` inside your workspace.
-2. Paste the JSON block.
-3. Reload the window; run **MCP: Show Installed Servers** to verify.
----
-## 5 – Verify connectivity
-```bash
-npx mcp-remote https://prod.api.elementary-data.com/mcp/ \
-  --header "Authorization: Bearer $AUTH_TOKEN" --health
-```
-`200 OK` confirms the endpoint and token are valid.
 
-## 6 – Troubleshooting
-| Symptom | Remedy |
-|---------|--------|
-| `node: command not found` | Install Node ≥ 18 and ensure it’s on `PATH`. |
-| `401 Unauthorized` | Token expired or pasted incorrectly → regenerate. |
+#### 4.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
+
 ---
+
 ### Security reminders
 * Tokens confer **all** your Elementary permissions.  
 * Keep them secret and scoped; rotate when in doubt.