MCP docs and log spamming fix (#21087)
* first update of docs * fixes to docs * prevent log on mcp api key
Costa Tsaousis committed
Oct 2, 2025 at 15:58 UTC
db00eed678499541f8715db74486505be350a610
16 files changed
+588
-172
docs/learn/mcp.md
+152
-9
@@ -12,22 +12,25 @@ Every Netdata Agent and Parent includes an MCP server that:
12
13
Netdata MCP supports three transport mechanisms:
14
15
-| Transport | Endpoint | Use Case |
16
-|-----------|----------|----------|
17
-| **WebSocket** | `ws://YOUR_IP:19999/mcp` | Original transport, requires nd-mcp bridge for stdio clients |
18
-| **HTTP Streamable** | `http://YOUR_IP:19999/mcp` | Direct connection from AI clients supporting HTTP |
19
-| **SSE** | `http://YOUR_IP:19999/mcp?transport=sse` | Server-Sent Events for real-time streaming |
15
+| Transport | Endpoint | Use Case | Version Requirement |
16
+|-----------|----------|----------|---------------------|
17
+| **WebSocket** | `ws://YOUR_IP:19999/mcp` | Original transport, requires nd-mcp bridge for stdio clients | v2.6.0+ |
18
+| **HTTP Streamable** | `http://YOUR_IP:19999/mcp` | Direct connection from AI clients supporting HTTP | v2.7.2+ |
19
+| **SSE** | `http://YOUR_IP:19999/mcp?transport=sse` | Server-Sent Events for real-time streaming | v2.7.2+ |
20
+
21
+**Important:** MCP support requires Netdata v2.6.0 or later. If you're running v2.6.x through v2.7.1, you must use WebSocket transport via the `nd-mcp` bridge. HTTP and SSE transports are only available in v2.7.2 and later.
22
23
### Direct Connection vs Bridge
24
23
-With the new HTTP and SSE transports, many AI clients can now connect directly to Netdata without needing the nd-mcp bridge:
25
+With the new HTTP and SSE transports (v2.7.2+), many AI clients can now connect directly to Netdata without needing the nd-mcp bridge:
26
25
-- **Direct Connection**: AI clients that support HTTP or SSE transports can connect directly to Netdata
26
-- **Bridge Required**: AI clients that only support stdio (like some desktop apps) still need the nd-mcp bridge or the official MCP remote client
27
+- **Direct Connection** (v2.7.2+): AI clients that support HTTP or SSE transports can connect directly to Netdata
28
+- **Bridge Required**: AI clients that only support stdio (like some desktop apps) need the nd-mcp bridge or the official MCP remote client
29
+- **WebSocket Only** (v2.6.0 - v2.7.1): Older Netdata versions only support WebSocket, requiring the nd-mcp bridge for all connections
30
31
### Official MCP Remote Client
32
30
-If your AI client doesn't support HTTP/SSE directly and you don't want to use nd-mcp, you can use the official MCP remote client:
33
+If your AI client doesn't support HTTP/SSE directly and you don't want to use nd-mcp, you can use the official MCP remote client (requires Netdata v2.7.2+):
34
35
```bash
36
# Export your MCP key once per shell
@@ -44,6 +47,8 @@ npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
47
--header "Authorization: Bearer $NETDATA_MCP_API_KEY"
48
```
49
50
+**Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted.
51
+
52
## Visibility Scope
53
54
Netdata provides comprehensive access to all available observability data through MCP, including complete metadata:
@@ -203,6 +208,144 @@ Once you have nd-mcp (either from existing installation or built), test it:
208
# Press Ctrl+C to stop the test
209
```
210
211
+## Using MCP Remote Client
212
+
213
+The official MCP remote client (`mcp-remote`) is an alternative bridge that enables stdio-only AI clients to connect to Netdata's HTTP and SSE transports (requires Netdata v2.7.2+). Unlike nd-mcp which only supports WebSocket, mcp-remote provides broader transport compatibility.
214
+
215
+### When to Use MCP Remote
216
+
217
+Use `mcp-remote` when:
218
+- Your AI client only supports stdio communication
219
+- You want to use HTTP or SSE transports instead of WebSocket
220
+- You're running Netdata v2.7.2 or later
221
+- You don't want to build/install nd-mcp
222
+
223
+### Installation
224
+
225
+No installation required - `mcp-remote` runs via `npx`:
226
+
227
+```bash
228
+# Test the connection
229
+npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
230
+ --allow-http \
231
+ --header "Authorization: Bearer YOUR_API_KEY"
232
+```
233
+
234
+### Transport Options
235
+
236
+`mcp-remote` supports multiple transport strategies:
237
+
238
+```bash
239
+# HTTP transport (recommended)
240
+npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
241
+ --allow-http \
242
+ --header "Authorization: Bearer YOUR_API_KEY"
243
+
244
+# SSE transport
245
+npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
246
+ --allow-http \
247
+ --header "Authorization: Bearer YOUR_API_KEY"
248
+
249
+# Auto-detect with fallback (tries SSE first, falls back to HTTP)
250
+npx mcp-remote@latest --transport sse-first http://YOUR_NETDATA_IP:19999/mcp \
251
+ --allow-http \
252
+ --header "Authorization: Bearer YOUR_API_KEY"
253
+
254
+# HTTPS (no --allow-http flag needed)
255
+npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \
256
+ --header "Authorization: Bearer YOUR_API_KEY"
257
+```
258
+
259
+### Common Options
260
+
261
+| Option | Description | Example |
262
+|--------|-------------|---------|
263
+| `--http` | Use HTTP transport | `--http http://host:19999/mcp` |
264
+| `--sse` | Use SSE transport | `--sse http://host:19999/mcp` |
265
+| `--allow-http` | Allow non-HTTPS connections (required for HTTP URLs) | `--allow-http` |
266
+| `--header` | Add custom headers (for authentication) | `--header "Authorization: Bearer KEY"` |
267
+| `--transport` | Transport strategy | `--transport sse-first` (tries SSE, falls back to HTTP) |
268
+| `--debug` | Enable debug logging | `--debug` |
269
+| `--host` | OAuth callback host (default: localhost) | `--host 127.0.0.1` |
270
+| Port number | OAuth callback port (optional) | `9696` |
271
+
272
+### Authentication
273
+
274
+For Netdata MCP, pass the API key via the Authorization header:
275
+
276
+```bash
277
+# Using environment variable (recommended)
278
+export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
279
+
280
+npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
281
+ --allow-http \
282
+ --header "Authorization: Bearer $NETDATA_MCP_API_KEY"
283
+```
284
+
285
+**Security Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted.
286
+
287
+### Troubleshooting
288
+
289
+**Connection Issues:**
290
+```bash
291
+# Enable debug logging
292
+npx mcp-remote@latest --debug --http http://YOUR_NETDATA_IP:19999/mcp \
293
+ --allow-http \
294
+ --header "Authorization: Bearer YOUR_API_KEY"
295
+
296
+# Check debug logs (stored in ~/.mcp-auth/)
297
+cat ~/.mcp-auth/*_debug.log
298
+```
299
+
300
+**Clear Authentication State:**
301
+```bash
302
+# Remove cached credentials
303
+rm -rf ~/.mcp-auth
304
+```
305
+
306
+**Spaces in Arguments:**
307
+
308
+Some AI clients (Cursor, Claude Desktop on Windows) have issues with spaces in arguments. Use environment variables as a workaround:
309
+
310
+```json
311
+{
312
+ "mcpServers": {
313
+ "netdata": {
314
+ "command": "npx",
315
+ "args": [
316
+ "mcp-remote@latest",
317
+ "--http",
318
+ "http://YOUR_IP:19999/mcp",
319
+ "--allow-http",
320
+ "--header",
321
+ "Authorization:${AUTH_HEADER}"
322
+ ],
323
+ "env": {
324
+ "AUTH_HEADER": "Bearer YOUR_API_KEY"
325
+ }
326
+ }
327
+ }
328
+}
329
+```
330
+
331
+### Version Management
332
+
333
+Always use the latest version:
334
+
335
+```bash
336
+# Force npx to check for latest version
337
+npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp
338
+```
339
+
340
+Or in AI client configurations:
341
+```json
342
+{
343
+ "args": ["mcp-remote@latest", "--http", "..."]
344
+}
345
+```
346
+
347
+For more details, see the [official mcp-remote documentation](https://github.com/geelen/mcp-remote).
348
+
349
## Finding Your API Key
350
351
To access sensitive functions like logs and live system information, you need an API key. Netdata automatically generates an API key on startup. The key is stored in a file on the Netdata server you want to connect to.
docs/ml-ai/ai-chat-netdata/claude-desktop.md
+99
-15
@@ -2,12 +2,28 @@
2
3
Configure Claude Desktop to access your Netdata infrastructure through MCP.
4
5
+## Transport Support
6
+
7
+Claude Desktop launches MCP servers as child processes over `stdio` (the only transport the client supports today). Remote servers must be proxied through a launcher that exposes a stdio interface, such as `nd-mcp` or `npx mcp-remote`, before Claude Desktop can connect.
8
+
9
+| Transport delivered to Claude Desktop | Support | Netdata Version | Notes |
10
+|--------------------------------------|---------|-----------------|-------|
11
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Native Claude transport |
12
+| **stdio** (via `npx mcp-remote`) | ✅ Fully Supported | v2.7.2+ | Wraps Netdata HTTP/SSE in stdio |
13
+| **Direct HTTP / SSE** | ⚠️ Use bridge | - | Requires a stdio bridge (Claude cannot speak HTTP/SSE directly) |
14
+
15
+> **Reference:** Claude Desktop’s official quickstart configures MPC servers by editing `claude_desktop_config.json` and launching stdio bridges (https://modelcontextprotocol.io/docs/develop/connect-local-servers).
16
+
17
## Prerequisites
18
19
1. **Claude Desktop installed** - Download from [claude.ai/download](https://claude.ai/download)
8
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
9
-3. **`nd-mcp` program available on your desktop or laptop** - This is the bridge that translates `stdio` to `websocket`, connecting your AI Client to your Netdata Agent or Parent. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
10
-4. **Netdata MCP API key loaded into the environment** (recommended) - export it before launching Claude Code to avoid exposing it in config files:
20
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
21
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
22
+ - **v2.7.2+**: Can use `npx mcp-remote` bridge for HTTP/SSE support
23
+3. **Bridge required: Choose one:**
24
+ - `nd-mcp` bridge - The stdio-to-websocket bridge for all Netdata versions. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
25
+ - `npx mcp-remote@latest` - Official MCP remote client supporting HTTP/SSE (requires Netdata v2.7.2+)
26
+4. **Netdata MCP API key loaded into the environment** (recommended) - export it before launching Claude Desktop to avoid exposing it in config files:
27
```bash
28
export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
29
```
@@ -26,14 +42,31 @@ Use the community AppImage project:
42
1. Download from [github.com/fsoft72/claude-desktop-to-appimage](https://github.com/fsoft72/claude-desktop-to-appimage)
43
2. For best experience, install [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher)
44
29
-## Configuration
45
+## Configuration Methods
46
+
47
+Claude Desktop supports MCP servers through two methods: Custom Connectors for remote servers (recommended), and traditional JSON configuration (manual).
48
+
49
+### Method 1: Claude Desktop Custom Connectors (Anthropic-hosted beta)
50
+
51
+Anthropic’s custom connectors beta lets Team/Enterprise owners add remote servers through Claude’s UI. The connector flow relies on the server’s OAuth or custom auth and does **not** expose arbitrary HTTP headers. Follow the server developer’s instructions to complete the OAuth hand-off; the UI handles credential storage (https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
52
+
53
+Because Netdata currently authenticates via bearer tokens, you’ll need the stdio launcher methods below unless you front your Netdata MCP endpoint with an OAuth-capable bridge.
54
+
55
+### Method 2: Traditional JSON Configuration with nd-mcp Bridge
56
+
57
+For all Netdata versions (v2.6.0+), you can manually configure MCP servers:
58
59
1. Open Claude Desktop
60
2. Navigate to Settings:
61
- **Windows/Linux**: File → Settings → Developer (or `Ctrl+,`)
62
- **macOS**: Claude → Settings → Developer (or `Cmd+,`)
63
3. Click "Edit Config" button
36
-4. Add the Netdata configuration:
64
+4. This opens `claude_desktop_config.json` in your system’s config folder:
65
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
66
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
67
+ - **Linux** (preview builds): `~/.config/claude/claude_desktop_config.json`
68
+
69
+Add the Netdata configuration:
70
71
```json
72
{
@@ -48,14 +81,57 @@ Use the community AppImage project:
81
}
82
```
83
51
-Replace:
84
+5. Save the configuration file
85
+6. **Restart Claude Desktop** (required for changes to take effect)
86
53
-- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
54
-- `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
55
-- `ND_MCP_BEARER_TOKEN` - Export this environment variable with your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key) before launching Claude Desktop
87
+### Method 3: Traditional JSON Configuration with `npx mcp-remote` (v2.7.2+)
88
57
-5. Save the configuration
58
-6. **Restart Claude Desktop** (required for changes to take effect)
89
+For Netdata v2.7.2+ with HTTP/SSE support. `mcp-remote` wraps remote transports in a stdio session Claude can launch (https://modelcontextprotocol.io/docs/develop/connect-local-servers). Edit `claude_desktop_config.json` as above.
90
+
91
+```json
92
+{
93
+ "mcpServers": {
94
+ "netdata": {
95
+ "command": "npx",
96
+ "args": [
97
+ "mcp-remote@latest",
98
+ "--http",
99
+ "http://YOUR_NETDATA_IP:19999/mcp",
100
+ "--allow-http",
101
+ "--header",
102
+ "Authorization: Bearer NETDATA_MCP_API_KEY"
103
+ ]
104
+ }
105
+ }
106
+}
107
+```
108
+
109
+For SSE transport instead of HTTP:
110
+
111
+```json
112
+{
113
+ "mcpServers": {
114
+ "netdata": {
115
+ "command": "npx",
116
+ "args": [
117
+ "mcp-remote@latest",
118
+ "--sse",
119
+ "http://YOUR_NETDATA_IP:19999/mcp",
120
+ "--allow-http",
121
+ "--header",
122
+ "Authorization: Bearer NETDATA_MCP_API_KEY"
123
+ ]
124
+ }
125
+ }
126
+}
127
+```
128
+
129
+Replace in all examples:
130
+
131
+- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge) (nd-mcp method only)
132
+- `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
133
+- `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
134
+- `ND_MCP_BEARER_TOKEN` - Export this environment variable with your API key before launching Claude Desktop (nd-mcp method only)
135
136
## Verify Connection
137
@@ -77,11 +153,19 @@ Search the logs for authentication failures
153
154
## Multiple Environments
155
80
-Claude Desktop has limitations with multiple MCP servers. Options:
156
+Claude Desktop supports multiple environments:
157
+
158
+### Option 1: Multiple Custom Connectors (Recommended)
159
+
160
+Add multiple connectors for different environments via **Settings → Connectors**:
161
+
162
+- Add `Netdata Production` pointing to `http://prod-parent:19999/mcp`
163
+- Add `Netdata Staging` pointing to `http://stage-parent:19999/mcp`
164
+- Enable/disable connectors as needed
165
82
-### Option 1: Toggle Servers
166
+### Option 2: Toggle JSON Configuration
167
84
-Add multiple configurations and enable/disable as needed:
168
+For local bridges, add multiple configurations in `claude_desktop_config.json` and enable/disable as needed:
169
170
```json
171
{
@@ -102,7 +186,7 @@ Use the toggle switch in settings to enable only one at a time.
186
187
> ℹ️ Set `ND_MCP_BEARER_TOKEN` to the appropriate key before switching between environments to avoid storing secrets in the configuration file.
188
105
-### Option 2: Single Parent
189
+### Option 3: Single Parent
190
191
Connect to your main Netdata Parent that has visibility across all environments.
192
docs/ml-ai/ai-chat-netdata/cursor.md
+55
-14
@@ -2,32 +2,41 @@
2
3
Configure Cursor IDE to access your Netdata infrastructure through MCP.
4
5
+## Transport Support
6
+
7
+Cursor’s MCP client natively supports multiple transports (https://cursor.com/docs/context/mcp):
8
+
9
+| Transport | Support | Netdata Version | Notes |
10
+|-----------|---------|-----------------|-------|
11
+| **stdio** | ✅ Fully Supported | v2.6.0+ | Launch Netdata via `nd-mcp` or `npx mcp-remote` |
12
+| **SSE** | ✅ Fully Supported | v2.7.2+ | Configure `type: "sse"` with Netdata SSE endpoint |
13
+| **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Configure `type: "streamable-http"` for Netdata HTTP endpoint |
14
+| **WebSocket** | ❌ Not Supported | - | Use the stdio bridge for v2.6.0–v2.7.1 |
15
+
16
## Prerequisites
17
18
1. **Cursor installed** - Download from [cursor.com](https://www.cursor.com)
8
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
9
-3. **`nd-mcp` program available on your desktop or laptop** - This is the bridge that translates `stdio` to `websocket`, connecting your AI Client to your Netdata Agent or Parent. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
19
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
20
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport is available, so launch Netdata through `nd-mcp`
21
+ - **v2.7.2+**: Expose Netdata over SSE or HTTP directly, or continue to use `nd-mcp`
22
+3. **Optional bridge** - `npx mcp-remote@latest` remains useful if you prefer stdio-only setups or want to re-use the same launcher for multiple clients.
23
4. **Netdata MCP API key loaded into the environment** (recommended) - export it before launching Cursor:
24
```bash
25
export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
26
```
27
Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
28
16
-## Configuration
29
+## Configuration Methods
30
18
-1. Open Cursor
19
-2. Navigate to Settings:
20
- - **Windows/Linux**: File → Preferences → Settings (or `Ctrl+,`)
21
- - **macOS**: Cursor → Preferences → Settings (or `Cmd+,`)
22
-3. Search for "MCP" in settings
23
-4. Add your Netdata configuration to MCP Servers
31
+Cursor reads MCP definitions from `.cursor/mcp.json` in the workspace root. For user-wide defaults, open Cursor’s Settings and add the same structure to the global config path documented by Cursor (https://cursor.com/docs/context/mcp#configuration-locations).
32
25
-The configuration format:
33
+### Method 1: stdio Bridge (All Netdata versions)
34
35
```json
36
{
37
"mcpServers": {
38
"netdata": {
39
+ "type": "stdio",
40
"command": "/usr/sbin/nd-mcp",
41
"args": [
42
"ws://YOUR_NETDATA_IP:19999/mcp"
@@ -37,11 +46,41 @@ The configuration format:
46
}
47
```
48
40
-Replace:
49
+### Method 2: Direct SSE (Netdata v2.7.2+)
50
+
51
+```json
52
+{
53
+ "mcpServers": {
54
+ "netdata": {
55
+ "type": "sse",
56
+ "url": "https://YOUR_NETDATA_IP:19999/mcp",
57
+ "headers": {
58
+ "Authorization": "Bearer NETDATA_MCP_API_KEY"
59
+ }
60
+ }
61
+ }
62
+}
63
+```
64
+
65
+### Method 3: Streamable HTTP (Netdata v2.7.2+)
66
+
67
+```json
68
+{
69
+ "mcpServers": {
70
+ "netdata": {
71
+ "type": "streamable-http",
72
+ "url": "https://YOUR_NETDATA_IP:19999/mcp",
73
+ "headers": {
74
+ "Authorization": "Bearer NETDATA_MCP_API_KEY"
75
+ }
76
+ }
77
+ }
78
+}
79
+```
80
+
81
+> Cursor supports config interpolation such as `${env:NETDATA_MCP_API_KEY}` or `${workspaceFolder}` inside `command`, `args`, `env`, `url`, and `headers` (https://cursor.com/docs/context/mcp#config-interpolation). Use these to avoid storing secrets in plain text.
82
42
-- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
43
-- `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
44
-- `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
83
+After editing `.cursor/mcp.json`, restart Cursor or run “Reload Window” for the new server to appear in **Settings → MCP**.
84
85
## Using Netdata in Cursor
86
@@ -83,10 +122,12 @@ Cursor allows multiple MCP servers but requires manual toggling:
122
{
123
"mcpServers": {
124
"netdata-prod": {
125
+ "type": "stdio",
126
"command": "/usr/sbin/nd-mcp",
127
"args": ["ws://prod-parent:19999/mcp"]
128
},
129
"netdata-dev": {
130
+ "type": "stdio",
131
"command": "/usr/sbin/nd-mcp",
132
"args": ["ws://dev-parent:19999/mcp"]
133
}
docs/ml-ai/ai-chat-netdata/jetbrains-ides.md
+52
-9
@@ -14,12 +14,27 @@ Configure JetBrains IDEs to access your Netdata infrastructure through MCP.
14
- CLion
15
- RubyMine
16
17
+## Transport Support
18
+
19
+JetBrains AI Assistant currently communicates with MCP servers over `stdio` only (https://www.jetbrains.com/help/ai-assistant/mcp.html).
20
+
21
+| Transport | Support | Netdata Version | Notes |
22
+|-----------|---------|-----------------|-------|
23
+| **stdio** (via `nd-mcp`) | ✅ Fully Supported | v2.6.0+ | Launches bridge as subprocess |
24
+| **stdio** (via `npx mcp-remote`) | ✅ Fully Supported | v2.7.2+ | Wrap remote HTTP/SSE in stdio |
25
+| **Streamable HTTP / SSE** | ❌ Not Supported | - | Use a stdio launcher |
26
+| **WebSocket** | ❌ Not Supported | - | Accessible only through `nd-mcp` |
27
+
28
+> JetBrains documents a “workaround for remote servers” that relies on launching a stdio wrapper. Native HTTP/SSE support is not available yet.
29
+
30
## Prerequisites
31
32
1. **JetBrains IDE installed** - Any IDE from the list above
33
2. **AI Assistant plugin** - Install from IDE marketplace
21
-3. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
22
-4. **`nd-mcp` program available on your desktop or laptop** - This is the bridge that translates `stdio` to `websocket`, connecting your AI Client to your Netdata Agent or Parent. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
34
+3. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent for full infrastructure visibility.
35
+4. **Stdio launcher**:
36
+ - `nd-mcp` bridge - Required for Netdata versions that only expose WebSocket (v2.6.0–v2.7.1)
37
+ - `npx mcp-remote@latest` - Optional wrapper that exposes Netdata HTTP/SSE as stdio (useful for v2.7.2+)
38
5. **Netdata MCP API key exported before launching the IDE**:
39
```bash
40
export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
@@ -41,7 +56,9 @@ Configure JetBrains IDEs to access your Netdata infrastructure through MCP.
56
MCP support in JetBrains IDEs may require additional plugins or configuration. Check the plugin documentation for the latest setup instructions.
57
:::
58
44
-### Method 1: AI Assistant Settings
59
+### Method 1: Using nd-mcp Bridge (All Netdata versions v2.6.0+)
60
+
61
+**AI Assistant Settings:**
62
63
1. Go to Settings → Tools → AI Assistant
64
2. Look for MCP or External Tools configuration
@@ -57,9 +74,7 @@ MCP support in JetBrains IDEs may require additional plugins or configuration. C
74
}
75
```
76
60
-### Method 2: External Tools
61
-
62
-If direct MCP support is not available, configure as an External Tool:
77
+**External Tools (if AI Assistant doesn't support MCP directly):**
78
79
1. Go to Settings → Tools → External Tools
80
2. Click "+" to add new tool
@@ -68,11 +83,39 @@ If direct MCP support is not available, configure as an External Tool:
83
- **Program**: `/usr/sbin/nd-mcp`
84
- **Arguments**: `ws://YOUR_NETDATA_IP:19999/mcp`
85
71
-Replace:
86
+### Method 2: Using npx mcp-remote (Netdata v2.7.2+)
87
+
88
+For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client). JetBrains still launches this command over stdio; `mcp-remote` converts the remote HTTP/SSE session into the format AI Assistant understands.
89
+
90
+**AI Assistant Settings:**
91
+
92
+```json
93
+{
94
+ "name": "netdata",
95
+ "command": "npx",
96
+ "args": [
97
+ "mcp-remote@latest",
98
+ "--http",
99
+ "http://YOUR_NETDATA_IP:19999/mcp",
100
+ "--allow-http",
101
+ "--header",
102
+ "Authorization: Bearer NETDATA_MCP_API_KEY"
103
+ ]
104
+}
105
+```
106
+
107
+**External Tools:**
108
+
109
+- **Name**: Netdata MCP
110
+- **Program**: `npx`
111
+- **Arguments**: `mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp --allow-http --header "Authorization: Bearer NETDATA_MCP_API_KEY"`
112
+
113
+Replace in all examples:
114
73
-- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
115
+- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge) (nd-mcp method only)
116
- `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
75
-- `ND_MCP_BEARER_TOKEN` - Export with your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key) before launching the IDE
117
+- `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
118
+- `ND_MCP_BEARER_TOKEN` - Export with your API key before launching the IDE (nd-mcp method only)
119
120
## Usage in Different IDEs
121
docs/ml-ai/ai-chat-netdata/vs-code.md
+122
-47
@@ -12,12 +12,30 @@ The most popular open-source AI code assistant with MCP support.
12
13
Autonomous coding agent that can use MCP tools.
14
15
+## Transport Support
16
+
17
+VS Code extensions typically support stdio-based MCP servers:
18
+
19
+| Transport | Support | Netdata Version | Use Case |
20
+|-----------|---------|-----------------|----------|
21
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
22
+| **stdio** (via npx remote-mcp) | ✅ Fully Supported | v2.7.2+ | Alternative bridge with HTTP/SSE support |
23
+| **Streamable HTTP** | ⚠️ Varies by Extension | v2.7.2+ | Check extension documentation |
24
+| **SSE** (Server-Sent Events) | ⚠️ Varies by Extension | v2.7.2+ | Check extension documentation |
25
+| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge |
26
+
27
+> **Note:** Most VS Code extensions support stdio-based MCP servers. For HTTP/SSE connections to Netdata v2.7.2+, you can use npx remote-mcp bridge. For older Netdata versions (v2.6.0 - v2.7.1), use the nd-mcp bridge with WebSocket.
28
+
29
## Prerequisites
30
31
1. **VS Code installed** - [Download VS Code](https://code.visualstudio.com)
32
2. **MCP-compatible extension** - Install from VS Code Marketplace
19
-3. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
20
-4. **`nd-mcp` program available on your desktop or laptop** - This is the bridge that translates `stdio` to `websocket`, connecting your AI Client to your Netdata Agent or Parent. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
33
+3. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
34
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
35
+ - **v2.7.2+**: Can use `npx mcp-remote` bridge for HTTP/SSE support
36
+4. **Bridge required: Choose one:**
37
+ - `nd-mcp` bridge - The stdio-to-websocket bridge for all Netdata versions. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
38
+ - `npx mcp-remote@latest` - Official MCP remote client supporting HTTP/SSE (requires Netdata v2.7.2+)
39
5. **Netdata MCP API key exported before launching VS Code** - keep secrets out of config files by setting:
40
```bash
41
export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
@@ -48,26 +66,59 @@ Autonomous coding agent that can use MCP tools.
66
67
#### Step 2: Add Netdata MCP Server
68
51
-1. Click "**MCP**" in the top toolbar
52
-2. Click "**+ Add MCP Servers**"
53
-3. It creates the file in your current project's `.continue/mcpServers/` directory as `new-mcp-server.yaml`. You might want to rename the file to something more descriptive like `netdata.yaml` after editing.
54
-4. Replace the content with:
55
- ```yaml
56
- name: Netdata MCP
57
- version: 0.0.1
58
- schema: v1
59
- mcpServers:
60
- - name: netdata
61
- command: /usr/sbin/nd-mcp
62
- args:
63
- - ws://YOUR_NETDATA_IP:19999/mcp
64
- env: {}
65
- ```
66
-5. Replace:
67
- - `/usr/sbin/nd-mcp` with your actual nd-mcp path
68
- - `YOUR_NETDATA_IP` with your Netdata instance IP/hostname
69
- - `ND_MCP_BEARER_TOKEN` exported with your Netdata MCP API key before launching VS Code
70
-6. Save the file
69
+Continue stores MCP definitions as YAML or JSON blocks. The recommended flow is:
70
+
71
+1. Click "**MCP**" in the Continue toolbar
72
+2. Click "**+ Add MCP Servers**" to scaffold `.continue/mcpServers/<name>.yaml`
73
+3. Replace the contents with one of the configurations below
74
+
75
+> Continue’s reference guide documents the `type` field (`stdio`, `sse`, or `streamable-http`) and block syntax (https://docs.continue.dev/customize/deep-dives/mcp).
76
+
77
+**Method 1: stdio launcher (all Netdata versions)**
78
+
79
+```yaml
80
+name: Netdata (nd-mcp)
81
+version: 0.0.1
82
+schema: v1
83
+mcpServers:
84
+ - name: netdata
85
+ type: stdio
86
+ command: /usr/sbin/nd-mcp
87
+ args:
88
+ - ws://YOUR_NETDATA_IP:19999/mcp
89
+```
90
+
91
+Export `ND_MCP_BEARER_TOKEN` before launching Continue so `nd-mcp` can authenticate without embedding secrets in YAML.
92
+
93
+**Method 2: Direct SSE (Netdata v2.7.2+)**
94
+
95
+```yaml
96
+name: Netdata (SSE)
97
+version: 0.0.1
98
+schema: v1
99
+mcpServers:
100
+ - name: netdata
101
+ type: sse
102
+ url: https://YOUR_NETDATA_IP:19999/mcp
103
+ headers:
104
+ Authorization: Bearer ${NETDATA_MCP_API_KEY}
105
+```
106
+
107
+**Method 3: Streamable HTTP (Netdata v2.7.2+)**
108
+
109
+```yaml
110
+name: Netdata (HTTP)
111
+version: 0.0.1
112
+schema: v1
113
+mcpServers:
114
+ - name: netdata
115
+ type: streamable-http
116
+ url: https://YOUR_NETDATA_IP:19999/mcp
117
+ headers:
118
+ Authorization: Bearer ${NETDATA_MCP_API_KEY}
119
+```
120
+
121
+Continue expands environment placeholders such as `${NETDATA_MCP_API_KEY}` so you can keep API keys out of source control. After saving, reload the window to pick up the new server.
122
123
### Usage
124
@@ -88,24 +139,49 @@ Press `Ctrl+L` to open Continue chat, then:
139
140
### Configuration
141
91
-1. Open Settings (Ctrl+,)
92
-2. Search for "Cline MCP"
93
-3. Add configuration:
142
+Cline’s official docs describe two workflows (https://docs.cline.bot/mcp/configuring-mcp-servers):
143
+
144
+- **UI configuration** – Click the MCP Servers icon → Configure tab → add/update servers, restart, toggle, and set timeouts.
145
+- **JSON configuration** – Click **Configure MCP Servers** to open `cline_mcp_settings.json` and edit the underlying JSON.
146
+
147
+#### JSON examples
148
+
149
+**Stdio (`nd-mcp`)**
150
151
```json
152
{
97
- "cline.mcpServers": [
98
- {
99
- "name": "netdata",
153
+ "mcpServers": {
154
+ "netdata": {
155
"command": "/usr/sbin/nd-mcp",
156
"args": [
157
"ws://YOUR_NETDATA_IP:19999/mcp"
103
- ]
158
+ ],
159
+ "alwaysAllow": [],
160
+ "disabled": false
161
}
105
- ]
162
+ }
163
+}
164
+```
165
+
166
+**SSE for Netdata v2.7.2+**
167
+
168
+```json
169
+{
170
+ "mcpServers": {
171
+ "netdata": {
172
+ "url": "https://YOUR_NETDATA_IP:19999/mcp",
173
+ "headers": {
174
+ "Authorization": "Bearer NETDATA_MCP_API_KEY"
175
+ },
176
+ "alwaysAllow": [],
177
+ "disabled": false
178
+ }
179
+ }
180
}
181
```
182
183
+> Optional fields such as `networkTimeout`, `alwaysAllow`, and `env` map directly to Cline’s UI controls. SSE and stdio are the two transports Cline supports today; pick the one that matches your Netdata deployment.
184
+
185
### Usage
186
187
1. Open Cline (Ctrl+Shift+P → "Cline: Open Chat")
@@ -124,30 +200,29 @@ Create a Python script that checks Netdata for high CPU usage and sends an alert
200
201
### Workspace-Specific Configuration
202
127
-Create `.vscode/settings.json` in your project:
128
-
129
-```json
130
-{
131
- "continue.mcpServers": {
132
- "netdata-prod": {
133
- "command": "/usr/sbin/nd-mcp",
134
- "args": [
135
- "ws://prod-parent:19999/mcp"
136
- ]
137
- }
138
- }
139
-}
203
+Create a YAML file in your project's `.continue/mcpServers/` directory (e.g., `netdata-prod.yaml`):
204
+
205
+```yaml
206
+name: Netdata Production
207
+version: 0.0.1
208
+schema: v1
209
+mcpServers:
210
+ - name: netdata-prod
211
+ type: stdio
212
+ command: /usr/sbin/nd-mcp
213
+ args:
214
+ - ws://prod-parent:19999/mcp
215
```
216
217
### Environment Switching
218
219
Different projects can have different Netdata connections:
220
146
-- `~/projects/frontend/.vscode/settings.json` → Frontend servers
147
-- `~/projects/backend/.vscode/settings.json` → Backend servers
148
-- `~/projects/infrastructure/.vscode/settings.json` → All servers
221
+- `~/projects/frontend/.continue/mcpServers/netdata.yaml` → Frontend servers
222
+- `~/projects/backend/.continue/mcpServers/netdata.yaml` → Backend servers
223
+- `~/projects/infrastructure/.continue/mcpServers/netdata.yaml` → All servers
224
150
-> ℹ️ Export `ND_MCP_BEARER_TOKEN` with the appropriate key before opening VS Code so the bridge picks up credentials without storing them in `.vscode/settings.json`.
225
+> ℹ️ Export `ND_MCP_BEARER_TOKEN` with the appropriate key before opening VS Code so the bridge picks up credentials without storing them in the YAML files.
226
227
## Advanced Usage
228
docs/ml-ai/ai-devops-copilot/claude-code.md
+15
-11
@@ -6,25 +6,29 @@ Configure Claude Code to access your Netdata infrastructure through MCP.
6
7
Claude Code supports multiple MCP transport types, giving you flexibility in how you connect to Netdata:
8
9
-| Transport | Support | Use Case |
10
-|-----------|---------|----------|
11
-| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | Local bridge to WebSocket |
12
-| **Streamable HTTP** | ✅ Fully Supported | Direct connection to Netdata's HTTP endpoint |
13
-| **SSE** (Server-Sent Events) | ⚠️ Limited Support | Legacy, being deprecated |
14
-| **WebSocket** | ❌ Not Supported | Use nd-mcp bridge or HTTP instead |
9
+| Transport | Support | Netdata Version | Use Case |
10
+|-----------|---------|-----------------|----------|
11
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
12
+| **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
13
+| **SSE** (Server-Sent Events) | ✅ Fully Supported | v2.7.2+ | Remote SCP servers that expose SSE |
14
+| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP/SSE wrappers |
15
16
## Prerequisites
17
18
1. **Claude Code installed** - Available at [anthropic.com/claude-code](https://www.anthropic.com/claude-code)
19
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
20
-3. **For stdio connections only: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections.
19
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
20
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
21
+ - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
22
+3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections on v2.7.2+.
23
4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
24
25
## Configuration Methods
26
27
Claude Code has comprehensive MCP server management capabilities. For detailed documentation on all configuration options and commands, see the [official Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).
28
27
-### Method 1: Direct HTTP Connection (Recommended)
29
+> **Reference:** Claude Code’s official guide documents HTTP, SSE, and stdio transports with both CLI and `.mcp.json` configurations (https://docs.claude.com/en/docs/claude-code/mcp).
30
+
31
+### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
32
33
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
34
@@ -61,9 +65,9 @@ claude mcp add netdata /usr/sbin/nd-mcp \
65
ws://YOUR_NETDATA_IP:19999/mcp
66
```
67
64
-### Method 3: Using npx remote-mcp (Alternative Bridge)
68
+### Method 3: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
69
66
-If nd-mcp is not available, you can use the official MCP remote client:
70
+If nd-mcp is not available, you can use the official MCP remote client (requires Netdata v2.7.2+). For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client).
71
72
```bash
73
# Using SSE transport
docs/ml-ai/ai-devops-copilot/codex-cli.md
+33
-17
@@ -4,25 +4,23 @@ Configure OpenAI's Codex CLI to access your Netdata infrastructure through MCP f
4
5
## Transport Support
6
7
-Codex CLI currently has limited MCP transport support:
7
+Codex CLI supports both stdio launchers and direct Streamable HTTP when the RMCP client is enabled (https://github.com/openai/codex/blob/main/docs/config.md#mcp-servers).
8
9
-| Transport | Support | Use Case |
10
-|-----------|---------|----------|
11
-| **stdio** (via nd-mcp bridge) | ✅ Supported | Local bridge to WebSocket |
12
-| **stdio** (via npx remote-mcp) | ✅ Supported | Alternative bridge with HTTP/SSE support |
13
-| **Streamable HTTP** | ❌ Not Supported | Use npx remote-mcp bridge |
14
-| **SSE** (Server-Sent Events) | ❌ Not Supported | Use npx remote-mcp bridge |
15
-| **WebSocket** | ❌ Not Supported | Use nd-mcp bridge |
16
-
17
-> **Note:** Codex CLI currently only supports stdio-based MCP servers. For HTTP/SSE connections to Netdata, you must use a bridge like nd-mcp or npx remote-mcp.
9
+| Transport | Support | Netdata Version | Notes |
10
+|-----------|---------|-----------------|-------|
11
+| **stdio** (via `nd-mcp`) | ✅ Supported | v2.6.0+ | Default transport |
12
+| **stdio** (via `npx mcp-remote`) | ✅ Supported | v2.7.2+ | Wraps Netdata HTTP/SSE in stdio |
13
+| **Streamable HTTP** | ✅ Supported | v2.7.2+ | Requires `experimental_use_rmcp_client = true` |
14
+| **SSE** | ❌ Not Supported | - | Use streamable HTTP or stdio bridge |
15
+| **WebSocket** | ❌ Not Supported | - | Use stdio bridge |
16
17
## Prerequisites
18
19
1. **OpenAI Codex CLI installed** - Available via npm, Homebrew, or direct download from [GitHub](https://github.com/openai/codex)
22
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
23
-3. **Bridge required: Choose one:**
24
- - `nd-mcp` bridge - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
25
- - `npx mcp-remote@latest` - Official MCP remote client supporting HTTP/SSE
20
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
21
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
22
+ - **v2.7.2+**: Can use `npx mcp-remote` bridge for HTTP/SSE support
23
+3. **Launcher** – Run Netdata through `nd-mcp` (always) or `npx mcp-remote` (useful when you want a single stdio launcher for multiple MCP clients). Direct HTTP is also available for v2.7.2+ when you enable the RMCP client.
24
4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
25
26
## Installation
@@ -44,9 +42,27 @@ brew install codex
42
43
Codex CLI uses a TOML configuration file at `~/.codex/config.toml` for MCP server settings.
44
47
-### Method 1: Using npx remote-mcp (Recommended for HTTP/SSE)
45
+### Method 1: Native Streamable HTTP (Recommended for v2.7.2+)
46
+
47
+Enable the RMCP client and point Codex directly at Netdata’s HTTP endpoint:
48
+
49
+```toml
50
+# ~/.codex/config.toml
51
+
52
+experimental_use_rmcp_client = true
53
+
54
+[mcp_servers.netdata]
55
+url = "https://YOUR_NETDATA_IP:19999/mcp"
56
+bearer_token = "${NETDATA_MCP_API_KEY}"
57
+startup_timeout_sec = 20
58
+tool_timeout_sec = 120
59
+```
60
+
61
+> `bearer_token` is sent as `Authorization: Bearer <token>`. Consider sourcing it from an environment variable to avoid plain-text secrets.
62
+
63
+### Method 2: Using `npx mcp-remote` (Works for HTTP or SSE)
64
49
-This method allows Codex CLI to connect to Netdata's HTTP/SSE endpoints through the official MCP remote client:
65
+This launcher wraps Netdata’s remote transports in stdio for clients that cannot speak HTTP directly or when you prefer a consistent launcher across tools. For detailed options, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client).
66
67
```toml
68
# ~/.codex/config.toml
@@ -80,7 +96,7 @@ args = [
96
]
97
```
98
83
-### Method 2: Using nd-mcp Bridge
99
+### Method 3: Using nd-mcp Bridge (WebSocket only)
100
101
For environments where nd-mcp is available and preferred:
102
docs/ml-ai/ai-devops-copilot/crush.md
+14
-12
@@ -6,18 +6,20 @@ Configure Crush by Charmbracelet to access your Netdata infrastructure through M
6
7
Crush has comprehensive MCP transport support, making it highly flexible for connecting to Netdata:
8
9
-| Transport | Support | Use Case |
10
-|-----------|---------|----------|
11
-| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | Local bridge to WebSocket |
12
-| **Streamable HTTP** | ✅ Fully Supported | Direct connection to Netdata's HTTP endpoint |
13
-| **SSE** (Server-Sent Events) | ✅ Fully Supported | Direct connection to Netdata's SSE endpoint |
14
-| **WebSocket** | ❌ Not Supported | Use nd-mcp bridge or HTTP/SSE instead |
9
+| Transport | Support | Netdata Version | Use Case |
10
+|-----------|---------|-----------------|----------|
11
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
12
+| **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
13
+| **SSE** (Server-Sent Events) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's SSE endpoint |
14
+| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP/SSE instead |
15
16
## Prerequisites
17
18
1. **Crush installed** - Available via npm, Homebrew, or direct download from [GitHub](https://github.com/charmbracelet/crush)
19
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
20
-3. **For stdio connections only: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections.
19
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
20
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
21
+ - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
22
+3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections on v2.7.2+.
23
4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
24
25
> Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching Crush so credentials never appear in command-line arguments or config files:
@@ -57,7 +59,7 @@ Crush uses JSON configuration files with the following priority:
59
2. `crush.json` (project-specific)
60
3. `~/.config/crush/crush.json` (global)
61
60
-### Method 1: Direct HTTP Connection (Recommended)
62
+### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
63
64
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
65
@@ -96,7 +98,7 @@ For HTTPS connections:
98
}
99
```
100
99
-### Method 2: Direct SSE Connection
101
+### Method 2: Direct SSE Connection (v2.7.2+)
102
103
Connect directly to Netdata's SSE endpoint for real-time streaming:
104
@@ -136,9 +138,9 @@ For environments where you prefer or need to use the bridge:
138
}
139
```
140
139
-### Method 4: Using npx remote-mcp (Alternative Bridge)
141
+### Method 4: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
142
141
-If nd-mcp is not available, use the official MCP remote client:
143
+If nd-mcp is not available, use the official MCP remote client (requires Netdata v2.7.2+). For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client).
144
145
```json
146
{
docs/ml-ai/ai-devops-copilot/gemini-cli.md
+14
-12
@@ -6,18 +6,20 @@ Configure Google's Gemini CLI to access your Netdata infrastructure through MCP
6
7
Gemini CLI supports all major MCP transport types, giving you maximum flexibility:
8
9
-| Transport | Support | Use Case |
10
-|-----------|---------|----------|
11
-| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | Local bridge to WebSocket |
12
-| **Streamable HTTP** | ✅ Fully Supported | Direct connection to Netdata's HTTP endpoint |
13
-| **SSE** (Server-Sent Events) | ✅ Fully Supported | Direct connection to Netdata's SSE endpoint |
14
-| **WebSocket** | ❌ Not Supported | Use nd-mcp bridge or HTTP/SSE instead |
9
+| Transport | Support | Netdata Version | Use Case |
10
+|-----------|---------|-----------------|----------|
11
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
12
+| **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
13
+| **SSE** (Server-Sent Events) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's SSE endpoint |
14
+| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP/SSE instead |
15
16
## Prerequisites
17
18
1. **Gemini CLI installed** - Available from [GitHub](https://github.com/google-gemini/gemini-cli)
19
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
20
-3. **For stdio connections only: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections.
19
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
20
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
21
+ - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
22
+3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections on v2.7.2+.
23
4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
24
25
## Installation
@@ -37,7 +39,7 @@ npm run build
39
40
Gemini CLI has built-in MCP server support. For detailed MCP configuration, see the [official MCP documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).
41
40
-### Method 1: Direct HTTP Connection (Recommended)
42
+### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
43
44
Connect directly to Netdata's HTTP endpoint without needing any bridge:
45
@@ -67,7 +69,7 @@ Or configure in `~/.gemini/settings.json`:
69
}
70
```
71
70
-### Method 2: Direct SSE Connection
72
+### Method 2: Direct SSE Connection (v2.7.2+)
73
74
Connect directly to Netdata's SSE endpoint:
75
@@ -121,9 +123,9 @@ Or configure in `~/.gemini/settings.json`:
123
}
124
```
125
124
-### Method 4: Using npx remote-mcp (Alternative Bridge)
126
+### Method 4: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
127
126
-If nd-mcp is not available, use the official MCP remote client:
128
+If nd-mcp is not available, use the official MCP remote client (requires Netdata v2.7.2+). For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client).
129
130
```bash
131
# Using CLI command with SSE
docs/ml-ai/ai-devops-copilot/opencode.md
+13
-11
@@ -6,20 +6,22 @@ Configure SST's OpenCode to access your Netdata infrastructure through MCP for t
6
7
OpenCode supports both local and remote MCP servers:
8
9
-| Transport | Support | Use Case |
10
-|-----------|---------|----------|
11
-| **stdio** (local) | ✅ Fully Supported | Local servers via nd-mcp bridge |
12
-| **Streamable HTTP** (remote) | ✅ Fully Supported | Direct connection to Netdata's HTTP endpoint |
13
-| **SSE** (Server-Sent Events) | ⚠️ Limited Support | Known issues with SSE servers |
14
-| **WebSocket** | ❌ Not Supported | Use nd-mcp bridge or HTTP instead |
9
+| Transport | Support | Netdata Version | Use Case |
10
+|-----------|---------|-----------------|----------|
11
+| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
12
+| **Streamable HTTP** (remote) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
13
+| **SSE** (Server-Sent Events) | ⚠️ Limited Support | v2.7.2+ | Known issues with SSE servers |
14
+| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP instead |
15
16
> **Note:** OpenCode has reported issues with SSE-based MCP servers ([GitHub Issue #834](https://github.com/sst/opencode/issues/834)). Use HTTP streamable transport for best compatibility.
17
18
## Prerequisites
19
20
1. **OpenCode installed** - Available via npm, brew, or direct download from [GitHub](https://github.com/sst/opencode)
21
-2. **The IP and port (usually 19999) of a running Netdata Agent** - Prefer a Netdata Parent to get infrastructure level visibility. Currently the latest nightly version of Netdata has MCP support (not released to the stable channel yet). Your AI Client (running on your desktop or laptop) needs to have direct network access to this IP and port.
22
-3. **For local connections only: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for remote HTTP connections.
21
+2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999).
22
+ - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
23
+ - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
24
+3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections on v2.7.2+.
25
4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
26
27
> Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching OpenCode to keep secrets out of configuration files:
@@ -46,7 +48,7 @@ curl -fsSL https://opencode.ai/install.sh | bash
48
49
OpenCode uses an `opencode.json` configuration file with MCP servers defined under the `mcp` key.
50
49
-### Method 1: Direct HTTP Connection (Recommended)
51
+### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
52
53
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
54
@@ -98,9 +100,9 @@ For environments where you prefer or need to use the bridge:
100
}
101
```
102
101
-### Method 3: Using npx remote-mcp (Alternative Bridge)
103
+### Method 3: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
104
103
-If nd-mcp is not available, use the official MCP remote client:
105
+If nd-mcp is not available, use the official MCP remote client (requires Netdata v2.7.2+). For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/learn/mcp.md#using-mcp-remote-client).
106
107
```json
108
{
src/web/api/http_auth.c
+1
-1
@@ -308,7 +308,7 @@ bool web_client_bearer_token_auth(struct web_client *w, const char *v) {
308
return rc;
309
310
#ifdef NETDATA_MCP_DEV_PREVIEW_API_KEY
311
- if (mcp_api_key_verify(v)) {
311
+ if (mcp_api_key_verify(v, true)) { // silent=true for speculative check
312
web_client_set_mcp_preview_key(w);
313
return true;
314
}
src/web/api/mcp_auth.c
+13
-10
@@ -117,31 +117,34 @@ void mcp_api_key_initialize(void) {
117
netdata_log_info("MCP: Developer preview API key initialized. Location: %s", path);
118
}
119
120
-bool mcp_api_key_verify(const char *api_key) {
120
+bool mcp_api_key_verify(const char *api_key, bool silent) {
121
if (!api_key || !*api_key) {
122
- netdata_log_error("MCP: No API key provided");
122
+ if (!silent)
123
+ netdata_log_error("MCP: No API key provided");
124
return false;
125
}
125
-
126
+
127
// Check if agent is claimed
128
if (!is_agent_claimed()) {
128
- netdata_log_error("MCP: API key authentication rejected - agent is not claimed to Netdata Cloud");
129
+ if (!silent)
130
+ netdata_log_error("MCP: API key authentication rejected - agent is not claimed to Netdata Cloud");
131
return false;
132
}
131
-
133
+
134
// Check if we have a loaded API key
135
if (!mcp_dev_preview_api_key[0]) {
134
- netdata_log_error("MCP: No API key loaded");
136
+ if (!silent)
137
+ netdata_log_error("MCP: No API key loaded");
138
return false;
139
}
137
-
140
+
141
// Compare the keys
142
bool valid = (strcmp(api_key, mcp_dev_preview_api_key) == 0);
140
-
141
- if (!valid) {
143
+
144
+ if (!valid && !silent) {
145
netdata_log_error("MCP: Invalid API key provided");
146
}
144
-
147
+
148
return valid;
149
}
150
src/web/api/mcp_auth.h
+2
-1
@@ -17,7 +17,8 @@ void mcp_api_key_initialize(void);
17
18
// Verify if the provided API key matches the stored one
19
// Returns true if valid and agent is claimed, false otherwise
20
-bool mcp_api_key_verify(const char *api_key);
20
+// silent: if true, suppresses error logging (for speculative checks)
21
+bool mcp_api_key_verify(const char *api_key, bool silent);
22
23
// Get the current API key (for display purposes)
24
// Returns a static buffer that should not be freed
src/web/mcp/adapters/mcp-http.c
+1
-1
@@ -74,7 +74,7 @@ static void mcp_http_apply_api_key(struct web_client *w) {
74
75
char api_key_buffer[MCP_DEV_PREVIEW_API_KEY_LENGTH + 1];
76
if (mcp_http_extract_api_key(w, api_key_buffer, sizeof(api_key_buffer)) &&
77
- mcp_api_key_verify(api_key_buffer)) {
77
+ mcp_api_key_verify(api_key_buffer, false)) { // silent=false for MCP requests
78
web_client_set_permissions(w, HTTP_ACCESS_ALL, HTTP_USER_ROLE_ADMIN, USER_AUTH_METHOD_GOD);
79
}
80
}
src/web/mcp/adapters/mcp-sse.c
+1
-1
@@ -33,7 +33,7 @@ static void mcp_sse_apply_api_key(struct web_client *w) {
33
34
char api_key_buffer[MCP_DEV_PREVIEW_API_KEY_LENGTH + 1];
35
if (mcp_http_extract_api_key(w, api_key_buffer, sizeof(api_key_buffer)) &&
36
- mcp_api_key_verify(api_key_buffer)) {
36
+ mcp_api_key_verify(api_key_buffer, false)) { // silent=false for MCP requests
37
web_client_set_permissions(w, HTTP_ACCESS_ALL, HTTP_USER_ROLE_ADMIN, USER_AUTH_METHOD_GOD);
38
}
39
}
src/web/websocket/websocket-handshake.c
+1
-1
@@ -353,7 +353,7 @@ short int websocket_handle_handshake(struct web_client *w) {
353
api_key_buffer[i] = '\0';
354
355
// Verify the API key
356
- if (mcp_api_key_verify(api_key_buffer)) {
356
+ if (mcp_api_key_verify(api_key_buffer, false)) { // silent=false for websocket MCP requests
357
// Override authentication with god mode
358
wsc->user_auth.access = HTTP_ACCESS_ALL;
359
wsc->user_auth.method = USER_AUTH_METHOD_GOD;