From c7ec46efa203102b3cc422dcc5cc7863c0995d76 Mon Sep 17 00:00:00 2001 From: Elazar Lachkar Date: Tue, 2 Jun 2026 11:20:07 +0300 Subject: [PATCH 1/4] Update MCP setup guide with OAuth --- docs/cloud/mcp/setup-guide.mdx | 116 +++++++++++++-------------------- 1 file changed, 44 insertions(+), 72 deletions(-) diff --git a/docs/cloud/mcp/setup-guide.mdx b/docs/cloud/mcp/setup-guide.mdx index eb3bb011c..a0edfb74d 100644 --- a/docs/cloud/mcp/setup-guide.mdx +++ b/docs/cloud/mcp/setup-guide.mdx @@ -4,92 +4,64 @@ 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. +## How it works -## 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. | +Elementary's MCP server uses the **Streamable HTTP** transport with **OAuth 2.1** and dynamic client registration for authentication. -> **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 -> ``` +When you start the MCP server for the first time, your client will open a browser window so you can log in with your Elementary account. No access tokens or API keys are required — the server uses your user permissions directly. ---- - -## 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). - -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. - -### 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. +The server is available at: +``` +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 -``` +## Configure your client -> **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. +Add the following to your MCP client configuration. ---- - -## 3 – Configure your client -Most MCP‑compatible clients read a JSON config that defines mcpServers. Use one of the following patterns. -```jsonc +```json 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 " - } + "Elementary": { + "url": "https://prod.api.elementary-data.com/mcp" } } } ``` -**Why the `-y` flag?** -It makes `npx` skip the interactive “install this package?” prompt. - -### Client‑specific steps - -#### 3.1 Cursor IDE -1. **Settings → Model Context Protocol → Add Custom Server** - or edit `~/.cursor/mcp.json` (global) / `/.cursor/mcp.json` (workspace). -2. Paste the JSON above. -3. Save – Cursor auto‑restarts its MCP agent. - -#### 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 - +### Cursor IDE + + + + Go to **Settings → Model Context Protocol → Add Custom Server**, or edit `~/.cursor/mcp.json` (global) / `/.cursor/mcp.json` (workspace). + + + Paste the JSON block above and save. Cursor will restart its MCP agent automatically. + + + The first time the server starts, a browser window opens. Log in with your Elementary account to complete authentication. + + + +### Claude Desktop + + + + In the menu bar, choose **Claude → Settings → Developer** and click **Edit** under **Local MCP Servers**. + + + Paste the JSON block above and save. + + + Quit and reopen Claude Desktop. On first launch, a browser window opens for authentication. + + + + +Re-authentication is only required when your session expires or you explicitly sign out. + From 6b5ca205399f0dfd65f18cc23f1de5b004807af0 Mon Sep 17 00:00:00 2001 From: Elazar Lachkar Date: Thu, 4 Jun 2026 10:09:17 +0300 Subject: [PATCH 2/4] docs: warn that trailing slash in MCP server URL is required Co-authored-by: Cursor --- docs/cloud/mcp/setup-guide.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/cloud/mcp/setup-guide.mdx b/docs/cloud/mcp/setup-guide.mdx index a0edfb74d..7158a8253 100644 --- a/docs/cloud/mcp/setup-guide.mdx +++ b/docs/cloud/mcp/setup-guide.mdx @@ -18,6 +18,8 @@ The server is available at: https://prod.api.elementary-data.com/mcp/ ``` +The trailing slash in the URL is required. Omitting it will cause the connection to fail. + --- ## Configure your client @@ -28,7 +30,8 @@ Add the following to your MCP client configuration. { "mcpServers": { "Elementary": { - "url": "https://prod.api.elementary-data.com/mcp" + "url": "https://prod.api.elementary-data.com/mcp/", + "type": "http" } } } From ee58da88182d824ef18ca5682fb263841fb28780 Mon Sep 17 00:00:00 2001 From: Elazar Lachkar Date: Thu, 4 Jun 2026 14:15:46 +0300 Subject: [PATCH 3/4] Keep token auth --- docs/cloud/mcp/setup-guide.mdx | 107 ++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 28 deletions(-) diff --git a/docs/cloud/mcp/setup-guide.mdx b/docs/cloud/mcp/setup-guide.mdx index 7158a8253..a56d68ee8 100644 --- a/docs/cloud/mcp/setup-guide.mdx +++ b/docs/cloud/mcp/setup-guide.mdx @@ -6,36 +6,91 @@ badge: "Elementary Cloud" This guide walks you through connecting any MCP-compatible client (Cursor, Claude Desktop, and others) to Elementary's remote MCP server. -## How it works - -Elementary's MCP server uses the **Streamable HTTP** transport with **OAuth 2.1** and dynamic client registration for authentication. - -When you start the MCP server for the first time, your client will open a browser window so you can log in with your Elementary account. No access tokens or API keys are required — the server uses your user permissions directly. - The server is available at: ``` https://prod.api.elementary-data.com/mcp/ ``` -The trailing slash in the URL is required. Omitting it will cause the connection to fail. +## Authentication ---- + + + Elementary's MCP server supports the **Streamable HTTP** transport with **OAuth 2.1** and dynamic client registration. -## Configure your client - -Add the following to your MCP client configuration. + 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). -```json filename="mcp.json" -{ - "mcpServers": { - "Elementary": { - "url": "https://prod.api.elementary-data.com/mcp/", - "type": "http" + ```json filename="mcp.json" + { + "mcpServers": { + "Elementary": { + "url": "https://prod.api.elementary-data.com/mcp/" + } + } } - } -} -``` + ``` + + + Re-authentication is only required when your session expires or you explicitly sign out. + + + + + Use this method for headless setups, CI environments, or any client that doesn't support browser-based OAuth. + + #### Prerequisites + + | 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. | + + + If you don't have Node.js installed, use [nvm](https://github.com/nvm-sh/nvm) for easy installation: + + ```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 + ``` + + + #### Generate an access token + + 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. + + ```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 " + } + } + } + } + ``` + + Replace `` with the token you generated above. + + + +--- + +## Configure your client ### Cursor IDE @@ -44,10 +99,10 @@ Add the following to your MCP client configuration. Go to **Settings → Model Context Protocol → Add Custom Server**, or edit `~/.cursor/mcp.json` (global) / `/.cursor/mcp.json` (workspace). - Paste the JSON block above and save. Cursor will restart its MCP agent automatically. + Paste the JSON block from the authentication tab above and save. Cursor restarts its MCP agent automatically. - The first time the server starts, a browser window opens. Log in with your Elementary account to complete authentication. + If using OAuth, a browser window opens on first launch. Log in with your Elementary account to complete authentication. @@ -58,13 +113,9 @@ Add the following to your MCP client configuration. In the menu bar, choose **Claude → Settings → Developer** and click **Edit** under **Local MCP Servers**. - Paste the JSON block above and save. + Paste the JSON block from the authentication tab above and save. - Quit and reopen Claude Desktop. On first launch, a browser window opens for authentication. + Quit and reopen Claude Desktop. If using OAuth, a browser window opens on first launch for authentication. - - -Re-authentication is only required when your session expires or you explicitly sign out. - From 4422f621d311605545fde1c4436f48219ef54097 Mon Sep 17 00:00:00 2001 From: Elazar Lachkar Date: Thu, 4 Jun 2026 14:21:13 +0300 Subject: [PATCH 4/4] Added mcp-remote install back --- docs/cloud/mcp/setup-guide.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/cloud/mcp/setup-guide.mdx b/docs/cloud/mcp/setup-guide.mdx index a56d68ee8..8f52daf10 100644 --- a/docs/cloud/mcp/setup-guide.mdx +++ b/docs/cloud/mcp/setup-guide.mdx @@ -20,6 +20,8 @@ https://prod.api.elementary-data.com/mcp/ 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": { @@ -64,6 +66,16 @@ https://prod.api.elementary-data.com/mcp/ 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": {