You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Remote MCP support (streamable http and sse) (#21036)
* prepare for multiple mcp headends
* fixed last
* updated todo list
* updated todo list
* Add HTTP and SSE adapters for MCP
* Select MCP SSE via Accept header
* MCP: add HTTP/SSE transport support and fix chunked responses
* MCP test client: await HTTP/SSE responses and harden SSE parsing
* docs: drop completed MCP Phase 1/2 tasks from TODO
* docs: renumber remaining MCP phases
* docs: document HTTP/SSE MCP transports and remote-mcp usage
* updated docs for mcp changes
* bearer token in mcp-test-client
* MCP authorization via http header
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,
https://github.com/netdata/netdata/edit/master/docs/netdata-assistant.md,AI powered troubleshooting assistant,Unpublished,AI and Machine Learning,
194
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.
Copy file name to clipboardExpand all lines: docs/learn/mcp.md
+125-7Lines changed: 125 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,10 +4,46 @@ All Netdata Agents and Parents are Model Context Protocol (MCP) servers, enablin
4
4
5
5
Every Netdata Agent and Parent includes an MCP server that:
6
6
7
-
- Implements the protocol as WebSocket for transport
7
+
- Implements the protocol with multiple transport options: WebSocket, HTTP streamable, and SSE (Server-Sent Events)
8
8
- Provides read-only access to metrics, logs, alerts, and live system information
9
9
- Requires no additional installation - it's part of Netdata
10
10
11
+
## Transport Options
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 |
20
+
21
+
### Direct Connection vs Bridge
22
+
23
+
With the new HTTP and SSE transports, many AI clients can now connect directly to Netdata without needing the nd-mcp bridge:
24
+
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
+
28
+
### Official MCP Remote Client
29
+
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:
Netdata provides comprehensive access to all available observability data through MCP, including complete metadata:
@@ -22,7 +58,7 @@ Netdata provides comprehensive access to all available observability data throug
22
58
-**Function Execution** - Execute Netdata functions on any connected node (requires Netdata Parent)
23
59
-**Log Exploration** - Access logs from any connected node (requires Netdata Parent)
24
60
25
-
For sensitive features currently protected by Netdata Cloud SSO, a temporary MCP API key is generated on each Netdata instance. When included in the MCP connection string, 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.
61
+
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.
26
62
27
63
AI assistants have different visibility depending on where they connect:
28
64
@@ -32,6 +68,13 @@ AI assistants have different visibility depending on where they connect:
32
68
33
69
## Finding the nd-mcp Bridge
34
70
71
+
> **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.
72
+
73
+
The nd-mcp bridge is only needed for AI clients that:
74
+
- Only support `stdio` communication (like some desktop applications)
75
+
- Cannot use HTTP or SSE transports directly
76
+
- Cannot use `npx mcp-remote@latest`
77
+
35
78
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.
36
79
37
80
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:
@@ -201,15 +244,74 @@ If the file doesn't exist:
201
244
202
245
## AI Client Configuration
203
246
204
-
Most AI clients use a similar configuration format:
247
+
AI clients can connect to Netdata MCP in different ways depending on their transport support:
248
+
249
+
### Direct Connection (HTTP/SSE)
250
+
251
+
For AI clients that support HTTP or SSE transports:
Note: Most AI clients have difficulty choosing between multiple MCP servers. You may need to enable/disable them manually.
347
+
348
+
### Legacy Query String Support
349
+
350
+
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.
351
+
352
+
## AI Client Specific Documentation
353
+
354
+
For detailed configuration instructions for specific AI clients, see:
355
+
356
+
-[Claude Code](/docs/ml-ai/ai-devops-copilot/claude-code.md) - Anthropic's CLI for Claude
Copy file name to clipboardExpand all lines: docs/ml-ai/ai-chat-netdata/claude-desktop.md
+11-5Lines changed: 11 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,11 @@ Configure Claude Desktop to access your Netdata infrastructure through MCP.
7
7
1.**Claude Desktop installed** - Download from [claude.ai/download](https://claude.ai/download)
8
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
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.**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)
10
+
4.**Netdata MCP API key loaded into the environment** (recommended) - export it before launching Claude Code to avoid exposing it in config files:
-`/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/learn/mcp.md#finding-the-nd-mcp-bridge)
50
54
-`YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
51
-
-`NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/learn/mcp.md#finding-your-api-key)
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
52
56
53
57
5. Save the configuration
54
58
6.**Restart Claude Desktop** (required for changes to take effect)
@@ -84,18 +88,20 @@ Add multiple configurations and enable/disable as needed:
Copy file name to clipboardExpand all lines: docs/ml-ai/ai-chat-netdata/cursor.md
+10-4Lines changed: 10 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,11 @@ Configure Cursor IDE to access your Netdata infrastructure through MCP.
7
7
1.**Cursor installed** - Download from [cursor.com](https://www.cursor.com)
8
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
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.**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)
10
+
4.**Netdata MCP API key loaded into the environment** (recommended) - export it before launching Cursor:
Use the toggle in settings to enable only the environment you need.
94
98
99
+
> ℹ️ Before switching environments, set `ND_MCP_BEARER_TOKEN` to the matching key so the bridge picks up the correct credentials without embedding them in the config file.
Copy file name to clipboardExpand all lines: docs/ml-ai/ai-chat-netdata/jetbrains-ides.md
+8-4Lines changed: 8 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,11 @@ Configure JetBrains IDEs to access your Netdata infrastructure through MCP.
20
20
2.**AI Assistant plugin** - Install from IDE marketplace
21
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
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)
23
-
5.**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)
23
+
5.**Netdata MCP API key exported before launching the IDE**:
0 commit comments