Register Netdata to MCP Registry (#21088)
* home for Netdata MCP in docs * remote-mcp -> mcp-remote * fixed server.json * added mcp registry update on every netdata release
Costa Tsaousis committed
Oct 2, 2025 at 18:55 UTC
31235fe9fbcaeec10ece01ebd447bf3513ea6394
16 files changed
+350
-89
.github/workflows/release.yml
+60
@@ -250,3 +250,63 @@ jobs:
250
Trigger build: ${{ steps.trigger.outcome }}
251
SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }}
252
if: failure()
253
+
254
+ publish-mcp-registry:
255
+ name: Publish to MCP Registry
256
+ runs-on: ubuntu-latest
257
+ needs: update-changelogs
258
+ if: needs.update-changelogs.outputs.run == 'true' && needs.update-changelogs.outputs.type != 'nightly'
259
+ steps:
260
+ - name: Checkout
261
+ id: checkout
262
+ uses: actions/checkout@v5
263
+ with:
264
+ ref: ${{ needs.update-changelogs.outputs.ref }}
265
+ - name: Update server.json version
266
+ id: update-version
267
+ run: |
268
+ VERSION="${{ needs.update-changelogs.outputs.version }}"
269
+ # Remove 'v' prefix if present
270
+ VERSION="${VERSION#v}"
271
+ # Update version in server.json
272
+ sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" server.json
273
+ echo "Updated server.json to version: $VERSION"
274
+ - name: Install mcp-publisher
275
+ id: install
276
+ run: |
277
+ # Clone and build mcp-publisher
278
+ git clone https://github.com/modelcontextprotocol/registry.git /tmp/registry
279
+ cd /tmp/registry
280
+ make publisher
281
+ sudo cp bin/mcp-publisher /usr/local/bin/
282
+ mcp-publisher --version
283
+ - name: Authenticate with GitHub
284
+ id: auth
285
+ run: |
286
+ # GitHub Actions automatically provides GITHUB_TOKEN with OIDC
287
+ # mcp-publisher will use this for authentication
288
+ echo "Using GitHub OIDC authentication"
289
+ - name: Publish to registry
290
+ id: publish
291
+ env:
292
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
293
+ run: |
294
+ cd ${{ github.workspace }}
295
+ mcp-publisher publish server.json
296
+ - name: Failure Notification
297
+ uses: rtCamp/action-slack-notify@v2
298
+ env:
299
+ SLACK_COLOR: 'danger'
300
+ SLACK_FOOTER: ''
301
+ SLACK_ICON_EMOJI: ':github-actions:'
302
+ SLACK_TITLE: 'Failed to publish to MCP Registry:'
303
+ SLACK_USERNAME: 'GitHub Actions'
304
+ SLACK_MESSAGE: |-
305
+ ${{ github.repository }}: Failed to publish ${{ needs.update-changelogs.outputs.version }} to MCP Registry.
306
+ Checkout: ${{ steps.checkout.outcome }}
307
+ Update version: ${{ steps.update-version.outcome }}
308
+ Install mcp-publisher: ${{ steps.install.outcome }}
309
+ Authenticate: ${{ steps.auth.outcome }}
310
+ Publish: ${{ steps.publish.outcome }}
311
+ SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }}
312
+ if: failure()
docs/.map/map.csv
+13
-13
@@ -180,19 +180,19 @@ https://github.com/netdata/netdata/edit/master/docs/netdata-ai/troubleshooting/t
180
https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-anomaly-detection.md,Anomaly Detection,Published,Netdata AI/Anomaly Detection,
181
https://github.com/netdata/netdata/edit/master/src/ml/ml-configuration.md,ML Configuration,Published,Netdata AI/Anomaly Detection,
182
https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-accuracy.md,ML Accuracy,Published,Netdata AI/Anomaly Detection,"Analysis of Netdata's ML anomaly detection accuracy, false positive rates, and comparison with other approaches"
183
-https://github.com/netdata/netdata/edit/master/docs/learn/mcp.md,MCP,Published,Netdata AI/MCP,
184
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/ai-chat-netdata.md,Chat with Netdata,Published,Netdata AI/MCP,
185
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/ai-devops-copilot.md,MCP Clients,Published,Netdata AI/MCP/MCP Clients,
186
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/claude-desktop.md,Claude Desktop,Published,Netdata AI/MCP/MCP Clients,
187
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/cursor.md,Cursor,Published,Netdata AI/MCP/MCP Clients,
188
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/vs-code.md,Visual Studio Code,Published,Netdata AI/MCP/MCP Clients,
189
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/jetbrains-ides.md,JetBrains IDEs,Published,Netdata AI/MCP/MCP Clients,
190
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-chat-netdata/netdata-web-client.md,Netdata Web Client,Published,Netdata AI/MCP/MCP Clients,
191
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/claude-code.md,Claude Code,Published,Netdata AI/MCP/MCP Clients,
192
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/gemini-cli.md,Gemini CLI,Published,Netdata AI/MCP/MCP Clients,
193
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/codex-cli.md,OpenAI Codex CLI,Published,Netdata AI/MCP/MCP Clients,
194
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/crush.md,Crush,Published,Netdata AI/MCP/MCP Clients,
195
-https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-devops-copilot/opencode.md,OpenCode,Published,Netdata AI/MCP/MCP Clients,
183
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/README.md,MCP,Published,Netdata AI/MCP,
184
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/ai-chat-netdata.md,Chat with Netdata,Published,Netdata AI/MCP,
185
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md,MCP Clients,Published,Netdata AI/MCP/MCP Clients,
186
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/claude-desktop.md,Claude Desktop,Published,Netdata AI/MCP/MCP Clients,
187
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/cursor.md,Cursor,Published,Netdata AI/MCP/MCP Clients,
188
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/vs-code.md,Visual Studio Code,Published,Netdata AI/MCP/MCP Clients,
189
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md,JetBrains IDEs,Published,Netdata AI/MCP/MCP Clients,
190
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/netdata-web-client.md,Netdata Web Client,Published,Netdata AI/MCP/MCP Clients,
191
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/claude-code.md,Claude Code,Published,Netdata AI/MCP/MCP Clients,
192
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/gemini-cli.md,Gemini CLI,Published,Netdata AI/MCP/MCP Clients,
193
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/codex-cli.md,OpenAI Codex CLI,Published,Netdata AI/MCP/MCP Clients,
194
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/crush.md,Crush,Published,Netdata AI/MCP/MCP Clients,
195
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/opencode.md,OpenCode,Published,Netdata AI/MCP/MCP Clients,
196
,,,
197
https://github.com/netdata/netdata/edit/master/docs/netdata-assistant.md,AI powered troubleshooting assistant,Unpublished,AI and Machine Learning,
198
https://github.com/netdata/netdata/edit/master/src/ml/README.md,ML models and anomaly detection,Unpublished,AI and Machine Learning,This is an in-depth look at how Netdata uses ML to detect anomalies.
docs/netdata-ai/mcp/README.md
renamed
+57
-69
@@ -1,76 +1,63 @@
1
# Netdata MCP
2
3
-All Netdata Agents and Parents are Model Context Protocol (MCP) servers, enabling AI assistants to interact with your infrastructure monitoring data.
3
+All Netdata Agents and Parents (v2.6.0+) are Model Context Protocol (MCP) servers, enabling AI assistants to interact with your infrastructure monitoring data.
4
5
-Every Netdata Agent and Parent includes an MCP server that:
5
+Every Netdata Agent and Parent includes an MCP server, listening at same port the dashboard is listening at (default: `19999`).
6
7
-- Implements the protocol with multiple transport options: WebSocket, HTTP streamable, and SSE (Server-Sent Events)
8
-- Provides read-only access to metrics, logs, alerts, and live system information
9
-- Requires no additional installation - it's part of Netdata
7
+Netdata provides comprehensive access to all available observability data through MCP, including complete metadata:
8
11
-## Transport Options
9
+- **Node Discovery** - Hardware specifications, operating system details, version information, streaming topology, and associated metadata
10
+- **Metrics Discovery** - Full-text search capabilities across contexts, instances, dimensions, and labels
11
+- **Function Discovery** - Access to system functions including `processes`, `network-connections`, `streaming`, `systemd-journal`, `windows-events`, etc.
12
+- **Alert Discovery** - Real-time visibility into active and raised alerts
13
+- **Metrics Queries** - Complex aggregations and groupings with ML-powered anomaly detection
14
+- **Metrics Scoring** - Root cause analysis leveraging anomaly detection and metric correlations
15
+- **Alert History** - Complete alert transition logs and state changes
16
+- **Function Execution** - Execute Netdata functions on any connected node (requires Netdata Parent)
17
+- **Log Exploration** - Access logs from any connected node (requires Netdata Parent)
18
+
19
+For sensitive features currently protected by Netdata Cloud SSO, a temporary MCP API key is generated on each Netdata instance. When presented via the `Authorization: Bearer` header, this key unlocks access to sensitive data and protected functions (like `systemd-journal`, `windows-events` and `processes`). This temporary API key mechanism will eventually be replaced with a new authentication system integrated with Netdata Cloud.
20
13
-Netdata MCP supports three transport mechanisms:
21
+AI assistants have different visibility depending on where they connect:
22
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+ |
23
+- **Netdata Cloud**: (coming soon) Full visibility across all nodes in your infrastructure
24
+- **Netdata Parent Node**: Visibility across all child nodes connected to that parent
25
+- **Netdata Child/Standalone Node**: Visibility only into that specific node
26
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.
27
+## Transport Options
28
23
-### Direct Connection vs Bridge
29
+Netdata implements the MCP protocol with multiple transport options:
30
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:
31
+| Transport | Endpoint | Use Case | Version Requirement |
32
+|---------------------|----------------------------|--------------------------------------------------------------|----------------------|
33
+| **WebSocket** | `ws://YOUR_IP:19999/mcp` | Original transport, requires nd-mcp bridge for stdio clients | v2.6.0+ |
34
+| **HTTP Streamable** | `http://YOUR_IP:19999/mcp` | Direct connection from AI clients supporting HTTP | v2.7.2+ |
35
+| **SSE** | `http://YOUR_IP:19999/sse` | Server-Sent Events for real-time streaming | v2.7.2+ |
36
37
- **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
38
+- **Bridge Required**: AI clients that only support stdio need the `nd-mcp` (stdio-to-websocket) or `mcp-remote` (stdio-to-http or stdio-to-sse) bridge
39
31
-### Official MCP Remote Client
40
+### Official MCP Remote Client (mcp-remote)
41
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+):
42
+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+):
43
44
```bash
45
# Export your MCP key once per shell
46
export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
47
39
-# For SSE transport
40
-npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
48
+# For HTTP transport
49
+npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
50
--allow-http \
51
--header "Authorization: Bearer $NETDATA_MCP_API_KEY"
52
44
-# For HTTP transport
45
-npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
53
+# For SSE transport
54
+npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
55
--allow-http \
56
--header "Authorization: Bearer $NETDATA_MCP_API_KEY"
57
```
58
59
**Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted.
60
52
-## Visibility Scope
53
-
54
-Netdata provides comprehensive access to all available observability data through MCP, including complete metadata:
55
-
56
-- **Node Discovery** - Hardware specifications, operating system details, version information, streaming topology, and associated metadata
57
-- **Metrics Discovery** - Full-text search capabilities across contexts, instances, dimensions, and labels
58
-- **Function Discovery** - Access to system functions including `processes`, `network-connections`, `streaming`, `systemd-journal`, `windows-events`, etc.
59
-- **Alert Discovery** - Real-time visibility into active and raised alerts
60
-- **Metrics Queries** - Complex aggregations and groupings with ML-powered anomaly detection
61
-- **Metrics Scoring** - Root cause analysis leveraging anomaly detection and metric correlations
62
-- **Alert History** - Complete alert transition logs and state changes
63
-- **Function Execution** - Execute Netdata functions on any connected node (requires Netdata Parent)
64
-- **Log Exploration** - Access logs from any connected node (requires Netdata Parent)
65
-
66
-For sensitive features currently protected by Netdata Cloud SSO, a temporary MCP API key is generated on each Netdata instance. When presented via the `Authorization: Bearer` header, this key unlocks access to sensitive data and protected functions (like `systemd-journal`, `windows-events` and `processes`). This temporary API key mechanism will eventually be replaced with a new authentication system integrated with Netdata Cloud.
67
-
68
-AI assistants have different visibility depending on where they connect:
69
-
70
-- **Netdata Cloud**: (coming soon) Full visibility across all nodes in your infrastructure
71
-- **Netdata Parent Node**: Visibility across all child nodes connected to that parent
72
-- **Netdata Child/Standalone Node**: Visibility only into that specific node
73
-
61
## Finding the nd-mcp Bridge
62
63
> **Note**: With the new HTTP and SSE transports, many AI clients can now connect directly to Netdata without nd-mcp. Check your AI client's documentation to see if it supports direct HTTP or SSE connections.
@@ -80,8 +67,6 @@ The nd-mcp bridge is only needed for AI clients that:
67
- Cannot use HTTP or SSE transports directly
68
- Cannot use `npx mcp-remote@latest`
69
83
-AI clients like Claude Desktop run locally on your computer and use `stdio` communication. Since your Netdata runs remotely on a server, you need a bridge to convert `stdio` to WebSocket communication.
84
-
70
The `nd-mcp` bridge needs to be available on your desktop or laptop where your AI client runs. Since most users run Netdata on remote servers rather than their local machines, you have two options:
71
72
1. **If you have Netdata installed locally** - Use the existing nd-mcp
@@ -258,16 +243,16 @@ npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \
243
244
### Common Options
245
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` |
246
+| Option | Description | Example |
247
+|----------------|------------------------------------------------------|---------------------------------------------------------|
248
+| `--http` | Use HTTP transport | `--http http://host:19999/mcp` |
249
+| `--sse` | Use SSE transport | `--sse http://host:19999/mcp` |
250
+| `--allow-http` | Allow non-HTTPS connections (required for HTTP URLs) | `--allow-http` |
251
+| `--header` | Add custom headers (for authentication) | `--header "Authorization: Bearer KEY"` |
252
+| `--transport` | Transport strategy | `--transport sse-first` (tries SSE, falls back to HTTP) |
253
+| `--debug` | Enable debug logging | `--debug` |
254
+| `--host` | OAuth callback host (default: localhost) | `--host 127.0.0.1` |
255
+| Port number | OAuth callback port (optional) | `9696` |
256
257
### Authentication
258
@@ -318,11 +303,8 @@ Some AI clients (Cursor, Claude Desktop on Windows) have issues with spaces in a
303
"http://YOUR_IP:19999/mcp",
304
"--allow-http",
305
"--header",
321
- "Authorization:${AUTH_HEADER}"
322
- ],
323
- "env": {
324
- "AUTH_HEADER": "Bearer YOUR_API_KEY"
325
- }
306
+ "Authorization: Bearer YOUR_API_KEY"
307
+ ]
308
}
309
}
310
}
@@ -486,8 +468,6 @@ You can configure multiple Netdata instances:
468
}
469
```
470
489
-Note: Most AI clients have difficulty choosing between multiple MCP servers. You may need to enable/disable them manually.
490
-
471
### Legacy Query String Support
472
473
For compatibility with older tooling, Netdata still accepts the `?api_key=YOUR_API_KEY` query parameter on the `/mcp` endpoints. New integrations should prefer the `Authorization: Bearer YOUR_API_KEY` header, but the query-string form remains available if you are migrating gradually.
@@ -496,10 +476,18 @@ For compatibility with older tooling, Netdata still accepts the `?api_key=YOUR_A
476
477
For detailed configuration instructions for specific AI clients, see:
478
499
-- [Claude Code](/docs/ml-ai/ai-devops-copilot/claude-code.md) - Anthropic's CLI for Claude
500
-- [Gemini CLI](/docs/ml-ai/ai-devops-copilot/gemini-cli.md) - Google's Gemini CLI
501
-- [OpenAI Codex CLI](/docs/ml-ai/ai-devops-copilot/codex-cli.md) - OpenAI's Codex CLI
502
-- [Crush](/docs/ml-ai/ai-devops-copilot/crush.md) - Charmbracelet's glamorous terminal AI
503
-- [OpenCode](/docs/ml-ai/ai-devops-copilot/opencode.md) - SST's terminal-based AI assistant
479
+**Chat Clients:**
480
+- [Claude Desktop](/docs/netdata-ai/mcp/mcp-clients/claude-desktop.md) - Anthropic's desktop AI assistant
481
+- [Cursor](/docs/netdata-ai/mcp/mcp-clients/cursor.md) - AI-powered code editor
482
+- [Visual Studio Code](/docs/netdata-ai/mcp/mcp-clients/vs-code.md) - VS Code with MCP support
483
+- [JetBrains IDEs](/docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md) - IntelliJ, PyCharm, WebStorm, etc.
484
+- [Netdata Web Client](/docs/netdata-ai/mcp/mcp-clients/netdata-web-client.md) - Built-in web-based AI chat
485
+
486
+**DevOps Copilots:**
487
+- [Claude Code](/docs/netdata-ai/mcp/mcp-clients/claude-code.md) - Anthropic's CLI for Claude
488
+- [Gemini CLI](/docs/netdata-ai/mcp/mcp-clients/gemini-cli.md) - Google's Gemini CLI
489
+- [OpenAI Codex CLI](/docs/netdata-ai/mcp/mcp-clients/codex-cli.md) - OpenAI's Codex CLI
490
+- [Crush](/docs/netdata-ai/mcp/mcp-clients/crush.md) - Charmbracelet's glamorous terminal AI
491
+- [OpenCode](/docs/netdata-ai/mcp/mcp-clients/opencode.md) - SST's terminal-based AI assistant
492
493
Each guide includes specific transport support matrices and configuration examples optimized for that client.
docs/netdata-ai/mcp/ai-chat-netdata.md
renamed
docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md
renamed
docs/netdata-ai/mcp/mcp-clients/claude-code.md
renamed
+2
-2
@@ -65,7 +65,7 @@ claude mcp add netdata /usr/sbin/nd-mcp \
65
ws://YOUR_NETDATA_IP:19999/mcp
66
```
67
68
-### Method 3: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
68
+### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
69
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
@@ -171,7 +171,7 @@ Create `~/projects/production/.mcp.json`:
171
}
172
```
173
174
-#### Using npx remote-mcp
174
+#### Using npx mcp-remote
175
176
Create `~/projects/production/.mcp.json`:
177
docs/netdata-ai/mcp/mcp-clients/claude-desktop.md
renamed
docs/netdata-ai/mcp/mcp-clients/codex-cli.md
renamed
docs/netdata-ai/mcp/mcp-clients/crush.md
renamed
+1
-1
@@ -138,7 +138,7 @@ For environments where you prefer or need to use the bridge:
138
}
139
```
140
141
-### Method 4: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
141
+### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
142
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
docs/netdata-ai/mcp/mcp-clients/cursor.md
renamed
docs/netdata-ai/mcp/mcp-clients/gemini-cli.md
renamed
+1
-1
@@ -123,7 +123,7 @@ Or configure in `~/.gemini/settings.json`:
123
}
124
```
125
126
-### Method 4: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
126
+### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
127
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
docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md
renamed
docs/netdata-ai/mcp/mcp-clients/netdata-web-client.md
renamed
docs/netdata-ai/mcp/mcp-clients/opencode.md
renamed
+1
-1
@@ -100,7 +100,7 @@ For environments where you prefer or need to use the bridge:
100
}
101
```
102
103
-### Method 3: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
103
+### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
104
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
docs/netdata-ai/mcp/mcp-clients/vs-code.md
renamed
+2
-2
@@ -19,12 +19,12 @@ VS Code extensions typically support stdio-based MCP servers:
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 |
22
+| **stdio** (via npx mcp-remote) | ✅ 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.
27
+> **Note:** Most VS Code extensions support stdio-based MCP servers. For HTTP/SSE connections to Netdata v2.7.2+, you can use npx mcp-remote bridge. For older Netdata versions (v2.6.0 - v2.7.1), use the nd-mcp bridge with WebSocket.
28
29
## Prerequisites
30
server.json
new
+213
@@ -0,0 +1,213 @@
1
+{
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
3
+ "name": "io.github.netdata/mcp-server",
4
+ "description": "AI-powered infrastructure monitoring with real-time metrics, logs, alerts, and ML anomaly detection.",
5
+ "version": "2.7.1-1",
6
+ "homepage": "https://www.netdata.cloud",
7
+ "documentation": "https://learn.netdata.cloud/docs/netdata-ai/mcp",
8
+ "license": "GPL-3.0",
9
+ "repository": {
10
+ "url": "https://github.com/netdata/netdata",
11
+ "source": "github",
12
+ "subfolder": "docs/netdata-ai/mcp"
13
+ },
14
+ "capabilities": {
15
+ "features": [
16
+ "Real-time infrastructure observability",
17
+ "Per-second granularity with ML anomaly detection",
18
+ "System logs (systemd-journal, Windows events)",
19
+ "Live system functions (processes, network connections, systemd services, ipmi)",
20
+ "Alert history and transitions",
21
+ "Anomaly detection, metric correlation, root cause analysis, blast radius detection"
22
+ ],
23
+ "transports": [
24
+ "stdio (via nd-mcp bridge)",
25
+ "stdio (via npx mcp-remote)",
26
+ "HTTP Streamable (direct, v2.7.2+)",
27
+ "SSE (direct, v2.7.2+)",
28
+ "WebSocket (direct, v2.6.0+)"
29
+ ]
30
+ },
31
+ "configuration": {
32
+ "examples": {
33
+ "stdio_via_nd-mcp": {
34
+ "description": "Use system-installed nd-mcp bridge (all Netdata versions v2.6.0+)",
35
+ "config": {
36
+ "mcpServers": {
37
+ "netdata": {
38
+ "command": "/usr/bin/nd-mcp",
39
+ "args": [
40
+ "--bearer",
41
+ "${NETDATA_MCP_API_KEY}",
42
+ "ws://localhost:19999/mcp"
43
+ ]
44
+ }
45
+ }
46
+ },
47
+ "notes": [
48
+ "nd-mcp is installed with Netdata at /usr/bin/nd-mcp or /usr/sbin/nd-mcp",
49
+ "Supports WebSocket transport only",
50
+ "Get API key: sudo cat /var/lib/netdata/mcp_dev_preview_api_key"
51
+ ]
52
+ },
53
+ "stdio_via_npx_mcp-remote_http": {
54
+ "description": "Use official mcp-remote with HTTP transport (Netdata v2.7.2+)",
55
+ "config": {
56
+ "mcpServers": {
57
+ "netdata": {
58
+ "command": "npx",
59
+ "args": [
60
+ "mcp-remote@latest",
61
+ "--http",
62
+ "http://localhost:19999/mcp",
63
+ "--allow-http",
64
+ "--header",
65
+ "Authorization: Bearer ${NETDATA_MCP_API_KEY}"
66
+ ]
67
+ }
68
+ }
69
+ },
70
+ "notes": [
71
+ "Requires Netdata v2.7.2 or later (currently in nightly builds)",
72
+ "Use --allow-http for non-HTTPS connections",
73
+ "For HTTPS, remove --allow-http flag"
74
+ ]
75
+ },
76
+ "stdio_via_npx_mcp-remote_sse": {
77
+ "description": "Use official mcp-remote with SSE transport (Netdata v2.7.2+)",
78
+ "config": {
79
+ "mcpServers": {
80
+ "netdata": {
81
+ "command": "npx",
82
+ "args": [
83
+ "mcp-remote@latest",
84
+ "--sse",
85
+ "http://localhost:19999/mcp",
86
+ "--allow-http",
87
+ "--header",
88
+ "Authorization: Bearer ${NETDATA_MCP_API_KEY}"
89
+ ]
90
+ }
91
+ }
92
+ },
93
+ "notes": [
94
+ "Requires Netdata v2.7.2 or later (currently in nightly builds)",
95
+ "SSE provides real-time streaming",
96
+ "Alternative to HTTP transport"
97
+ ]
98
+ },
99
+ "direct_http": {
100
+ "description": "Direct HTTP connection (Netdata v2.7.2+, if AI client supports)",
101
+ "config": {
102
+ "mcpServers": {
103
+ "netdata": {
104
+ "type": "http",
105
+ "url": "http://localhost:19999/mcp",
106
+ "headers": {
107
+ "Authorization": "Bearer ${NETDATA_MCP_API_KEY}"
108
+ }
109
+ }
110
+ }
111
+ },
112
+ "notes": [
113
+ "Requires Netdata v2.7.2 or later",
114
+ "Only works if AI client supports HTTP transport directly",
115
+ "No bridge needed"
116
+ ]
117
+ },
118
+ "direct_sse": {
119
+ "description": "Direct SSE connection (Netdata v2.7.2+, if AI client supports)",
120
+ "config": {
121
+ "mcpServers": {
122
+ "netdata": {
123
+ "type": "sse",
124
+ "url": "http://localhost:19999/mcp?transport=sse",
125
+ "headers": {
126
+ "Authorization": "Bearer ${NETDATA_MCP_API_KEY}"
127
+ }
128
+ }
129
+ }
130
+ },
131
+ "notes": [
132
+ "Requires Netdata v2.7.2 or later",
133
+ "Only works if AI client supports SSE transport directly",
134
+ "No bridge needed"
135
+ ]
136
+ }
137
+ },
138
+ "authentication": {
139
+ "description": "Netdata MCP uses bearer token authentication for sensitive operations (logs, live system functions)",
140
+ "finding_api_key": [
141
+ "Default location: /var/lib/netdata/mcp_dev_preview_api_key",
142
+ "Static installations: /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key",
143
+ "Command: sudo cat /var/lib/netdata/mcp_dev_preview_api_key"
144
+ ],
145
+ "usage": [
146
+ "Set environment variable: export NETDATA_MCP_API_KEY=\"$(cat /var/lib/netdata/mcp_dev_preview_api_key)\"",
147
+ "Use ${NETDATA_MCP_API_KEY} in configuration files",
148
+ "Or pass directly via --bearer flag (nd-mcp) or --header flag (mcp-remote)"
149
+ ]
150
+ },
151
+ "remote_access": {
152
+ "description": "To connect to remote Netdata instances, replace localhost:19999 with your Netdata IP/hostname",
153
+ "examples": {
154
+ "production_parent": "ws://prod-parent.example.com:19999/mcp",
155
+ "staging_environment": "http://staging-netdata:19999/mcp",
156
+ "cloud_instance": "https://netdata.example.com:19999/mcp"
157
+ }
158
+ }
159
+ },
160
+ "installation": {
161
+ "netdata": {
162
+ "description": "Netdata Agent with built-in MCP server",
163
+ "methods": [
164
+ {
165
+ "name": "Kickstart script (recommended)",
166
+ "command": "wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh"
167
+ },
168
+ {
169
+ "name": "Docker",
170
+ "command": "docker run -d --name=netdata -p 19999:19999 netdata/netdata:latest"
171
+ },
172
+ {
173
+ "name": "Package managers",
174
+ "platforms": {
175
+ "Ubuntu/Debian": "apt install netdata",
176
+ "RHEL/CentOS": "yum install netdata",
177
+ "macOS": "brew install netdata"
178
+ }
179
+ }
180
+ ],
181
+ "documentation": "https://learn.netdata.cloud/docs/netdata-agent/installation"
182
+ },
183
+ "nd-mcp": {
184
+ "description": "stdio-to-WebSocket bridge (installed automatically with Netdata)",
185
+ "locations": [
186
+ "/usr/bin/nd-mcp",
187
+ "/usr/sbin/nd-mcp",
188
+ "/opt/netdata/usr/bin/nd-mcp (static installations)",
189
+ "/usr/local/netdata/usr/bin/nd-mcp (built from source)",
190
+ "C:\\Program Files\\Netdata\\usr\\bin\\nd-mcp.exe (Windows)"
191
+ ],
192
+ "verify": "which nd-mcp || find / -name nd-mcp 2>/dev/null"
193
+ }
194
+ },
195
+ "version_compatibility": {
196
+ "v2.6.0-v2.7.1": {
197
+ "transports": ["WebSocket"],
198
+ "required_bridge": "nd-mcp",
199
+ "direct_connection": false
200
+ },
201
+ "v2.7.2+": {
202
+ "transports": ["WebSocket", "HTTP Streamable", "SSE"],
203
+ "required_bridge": "nd-mcp or mcp-remote (optional for stdio clients)",
204
+ "direct_connection": true,
205
+ "notes": "Currently available in nightly builds"
206
+ }
207
+ },
208
+ "support": {
209
+ "documentation": "https://learn.netdata.cloud/docs/netdata-ai/mcp",
210
+ "community": "https://discord.gg/netdata",
211
+ "issues": "https://github.com/netdata/netdata/issues"
212
+ }
213
+}