feat: Adds Netdata Cloud MCP server docs (#21736)
* feat: Adds Netdata Cloud MCP server docs * fix: Address PR review issues in MCP client docs - Add missing prerequisite that nodes must be claimed to Netdata Cloud across all MCP client docs (not just claude-code.md) - Fix Gemini CLI Cloud MCP config to use `httpUrl` instead of `url` (matching HTTP transport expectations) - Fix Cline Cloud MCP config in vs-code.md to use mcp-remote bridge since Cline only supports stdio and SSE transports Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: Wrap long markdown lines to satisfy Codacy 80-char limit Break long prose lines (Prerequisites, "Connect to...", "Replace YOUR_..." and blockquotes) across multiple lines. Table rows and URLs inside markdown links are left as-is since they cannot be wrapped. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: Address Copilot review comments in MCP docs - Fix "loca" typo to "locally" in README.md - Use "Business plan" consistently (remove "/Homelab" reference) - Expand scope:mcp description in api-tokens.md with link to Cloud MCP docs - Expand "How it works" steps from 5 to 8 to match the Mermaid diagram Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Juan Cañete committed
Feb 12, 2026 at 12:26 UTC
e08c95d74ca703b6d1dbd1d009e916c2fa90a07e
12 files changed
+644
-107
docs/netdata-ai/mcp/README.md
+162
-37
@@ -1,10 +1,15 @@
1
# Netdata MCP
2
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.
3
+Netdata provides [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers that enable AI assistants to interact with your infrastructure monitoring data. You can connect via:
4
5
-Every Netdata Agent and Parent includes an MCP server, listening at same port the dashboard is listening at (default: `19999`).
5
+- **[Netdata Cloud](#netdata-cloud-mcp)** — A single cloud-hosted endpoint at `https://app.netdata.cloud/api/v1/mcp` with full visibility across all your nodes. No bridges, no firewall changes.
6
+- **[Local Agent or Parent](#local-agent-or-parent-mcp)** —
7
+ Connect directly to any Netdata Agent or Parent
8
+ (v2.6.0+) on your network at
9
+ `http://YOUR_IP:19999/mcp`.
10
7
-Netdata provides comprehensive access to all available observability data through MCP, including complete metadata:
11
+Both options provide comprehensive access to all
12
+available observability data through MCP:
13
14
- **Node Discovery** - Hardware specifications, operating system details, version information, streaming topology, and associated metadata
15
- **Metrics Discovery** - Full-text search capabilities across contexts, instances, dimensions, and labels
@@ -16,15 +21,135 @@ Netdata provides comprehensive access to all available observability data throug
21
- **Function Execution** - Execute Netdata functions on any connected node (requires Netdata Parent)
22
- **Log Exploration** - Access logs from any connected node (requires Netdata Parent)
23
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
-
24
AI assistants have different visibility depending on where they connect:
25
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
+| Connection | Visibility |
27
+|------------|-----------|
28
+| **Netdata Cloud** | All nodes across your entire infrastructure |
29
+| **Netdata Parent** | All child nodes connected to that parent |
30
+| **Netdata Child/Standalone** | Only that specific node |
31
+
32
+| Feature | Cloud MCP | Agent/Parent MCP |
33
+|---------|-----------|------------------|
34
+| **Scope** | All nodes | Single agent/parent |
35
+| **Endpoint** | `app.netdata.cloud/api/v1/mcp` | `YOUR_IP:19999/mcp` |
36
+| **Transport** | Streamable HTTP | HTTP, SSE, WebSocket |
37
+| **Authentication** | Cloud API token (`scope:mcp`) | Local MCP API key |
38
+| **Network access** | Internet only | Direct access to Netdata IP required |
39
+| **Local setup** | None | Bridge may be needed for some clients |
40
+
41
+## Netdata Cloud MCP
42
+
43
+Connect AI assistants to your entire Netdata Cloud
44
+infrastructure through a single MCP endpoint —
45
+no local setup, no bridges, no firewall changes.
46
+
47
+### Prerequisites
48
+
49
+1. **Netdata Cloud account** with a **Business plan**
50
+2. **API token** with `scope:mcp` — [Create one in API Tokens settings](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md)
51
+3. **Nodes claimed to Netdata Cloud** —
52
+ The Cloud MCP server can only access nodes
53
+ connected to your Netdata Cloud space
54
+
55
+### Endpoint
56
+
57
+```
58
+https://app.netdata.cloud/api/v1/mcp
59
+```
60
+
61
+**Transport:** Streamable HTTP (stateless, works behind load balancers and CDNs)
62
+
63
+### Authentication
64
+
65
+All requests to the Cloud MCP endpoint require a
66
+Bearer token in the `Authorization` header:
67
27
-## Transport Options
68
+```
69
+Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN
70
+```
71
+
72
+#### Creating an API Token
73
+
74
+1. Log in to [Netdata Cloud](https://app.netdata.cloud)
75
+2. Click your profile picture in the bottom-left corner
76
+3. Select **User Settings**
77
+4. Navigate to the **API Tokens** section
78
+5. Create a new token with **`scope:mcp`**
79
+6. Copy and store the token securely — you won't be able to see it again
80
+
81
+For more details, see [API Tokens](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md).
82
+
83
+### Connection Configuration
84
+
85
+#### Generic MCP Client (HTTP Transport)
86
+
87
+For any MCP client that supports Streamable HTTP transport:
88
+
89
+```json
90
+{
91
+ "mcpServers": {
92
+ "netdata-cloud": {
93
+ "type": "http",
94
+ "url": "https://app.netdata.cloud/api/v1/mcp",
95
+ "headers": {
96
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
97
+ }
98
+ }
99
+ }
100
+}
101
+```
102
+
103
+#### Clients Requiring stdio Bridge
104
+
105
+For MCP clients that only support stdio transport, use `npx mcp-remote` as a bridge:
106
+
107
+```json
108
+{
109
+ "mcpServers": {
110
+ "netdata-cloud": {
111
+ "command": "npx",
112
+ "args": [
113
+ "mcp-remote@latest",
114
+ "https://app.netdata.cloud/api/v1/mcp",
115
+ "--header",
116
+ "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
117
+ ]
118
+ }
119
+ }
120
+}
121
+```
122
+
123
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
124
+[API token](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md)
125
+(must have `scope:mcp`).
126
+
127
+### Cloud MCP Troubleshooting
128
+
129
+#### Authentication Errors
130
+
131
+- Verify your API token has `scope:mcp`
132
+- Ensure the token is passed as `Authorization: Bearer <token>` (not as a query parameter)
133
+- Check that your Netdata Cloud subscription
134
+ includes a space in the Business plan
135
+
136
+#### No Nodes Visible
137
+
138
+- Confirm your nodes are claimed to Netdata Cloud and appear in the web dashboard
139
+- Check that agents are online and streaming to Cloud
140
+
141
+#### Connection Issues
142
+
143
+- The endpoint uses HTTPS — no `--allow-http` flag is needed
144
+- Test connectivity: `curl -H "Authorization: Bearer YOUR_TOKEN" https://app.netdata.cloud/api/v1/mcp`
145
+
146
+## Local Agent or Parent MCP
147
+
148
+Connect directly to any Netdata Agent or Parent on your network. All Netdata Agents and Parents (v2.6.0+) include a built-in MCP server at `http://YOUR_IP:19999/mcp`.
149
+
150
+Some MCP features — such as live process information, network connections, and full log access — are considered sensitive. These are protected by a local API key that Netdata generates automatically on startup. Without this key, AI assistants can still access metrics, alerts, and node information, but sensitive functions remain locked.
151
+
152
+### Transport Options
153
154
Netdata implements the MCP protocol with multiple transport options:
155
@@ -37,7 +162,7 @@ Netdata implements the MCP protocol with multiple transport options:
162
- **Direct Connection** (v2.7.2+): AI clients that support HTTP or SSE transports can connect directly to Netdata
163
- **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
164
40
-### Official MCP Remote Client (mcp-remote)
165
+#### Official MCP Remote Client (mcp-remote)
166
167
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+):
168
@@ -58,7 +183,7 @@ npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
183
184
**Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted.
185
61
-## Finding the nd-mcp Bridge
186
+### Finding the nd-mcp Bridge
187
188
> **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.
189
@@ -72,11 +197,11 @@ The `nd-mcp` bridge needs to be available on your desktop or laptop where your A
197
1. **If you have Netdata installed locally** - Use the existing nd-mcp
198
2. **If Netdata is only on remote servers** - Build nd-mcp on your desktop/laptop
199
75
-### Option 1: Using Existing nd-mcp
200
+#### Option 1: Using Existing nd-mcp
201
202
If you have Netdata installed on your desktop/laptop, find the existing bridge:
203
79
-#### Linux
204
+##### Linux
205
206
```bash
207
# Try these locations in order:
@@ -97,7 +222,7 @@ Common locations:
222
- **Static installations**: `/opt/netdata/usr/bin/nd-mcp`
223
- **Built from source**: `/usr/local/netdata/usr/bin/nd-mcp`
224
100
-#### macOS
225
+##### macOS
226
227
```bash
228
# Try these locations:
@@ -110,7 +235,7 @@ ls -la /opt/homebrew/bin/nd-mcp
235
find / -name "nd-mcp" 2>/dev/null
236
```
237
113
-#### Windows
238
+##### Windows
239
240
```powershell
241
# Check common locations:
@@ -120,9 +245,9 @@ dir "C:\Netdata\usr\bin\nd-mcp.exe"
245
where nd-mcp.exe
246
```
247
123
-### Option 2: Building nd-mcp for Your Desktop
248
+#### Option 2: Building nd-mcp for Your Desktop
249
125
-If you don't have Netdata installed loca you can build just the nd-mcp bridge. Netdata provides three implementations - choose the one that best fits your environment:
250
+If you don't have Netdata installed locally you can build just the nd-mcp bridge. Netdata provides three implementations - choose the one that best fits your environment:
251
252
1. **Go bridge** (recommended) - [Go bridge source code](https://github.com/netdata/netdata/tree/master/src/web/mcp/bridges/stdio-golang)
253
- Produces a single binary with no dependencies
@@ -179,7 +304,7 @@ pwd # Shows current directory
304
- Node.js bridge: `/path/to/bridges/stdio-nodejs/nd-mcp.js`
305
- Python bridge: `/path/to/bridges/stdio-python/nd-mcp.py`
306
182
-### Verify the Bridge Works
307
+#### Verify the Bridge Works
308
309
Once you have nd-mcp (either from existing installation or built), test it:
310
@@ -193,11 +318,11 @@ Once you have nd-mcp (either from existing installation or built), test it:
318
# Press Ctrl+C to stop the test
319
```
320
196
-## Using MCP Remote Client
321
+### Using MCP Remote Client
322
323
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.
324
200
-### When to Use MCP Remote
325
+#### When to Use MCP Remote
326
327
Use `mcp-remote` when:
328
- Your AI client only supports stdio communication
@@ -205,7 +330,7 @@ Use `mcp-remote` when:
330
- You're running Netdata v2.7.2 or later
331
- You don't want to build/install nd-mcp
332
208
-### Installation
333
+#### Installation
334
335
No installation required - `mcp-remote` runs via `npx`:
336
@@ -216,7 +341,7 @@ npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
341
--header "Authorization: Bearer YOUR_API_KEY"
342
```
343
219
-### Transport Options
344
+#### Transport Options
345
346
`mcp-remote` supports multiple transport strategies:
347
@@ -241,7 +366,7 @@ npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \
366
--header "Authorization: Bearer YOUR_API_KEY"
367
```
368
244
-### Common Options
369
+#### Common Options
370
371
| Option | Description | Example |
372
|----------------|------------------------------------------------------|---------------------------------------------------------|
@@ -254,7 +379,7 @@ npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \
379
| `--host` | OAuth callback host (default: localhost) | `--host 127.0.0.1` |
380
| Port number | OAuth callback port (optional) | `9696` |
381
257
-### Authentication
382
+#### Authentication
383
384
For Netdata MCP, pass the API key via the Authorization header:
385
@@ -269,7 +394,7 @@ npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
394
395
**Security Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted.
396
272
-### Troubleshooting
397
+#### Troubleshooting
398
399
**Connection Issues:**
400
```bash
@@ -310,7 +435,7 @@ Some AI clients (Cursor, Claude Desktop on Windows) have issues with spaces in a
435
}
436
```
437
313
-### Version Management
438
+#### Version Management
439
440
Always use the latest version:
441
@@ -328,7 +453,7 @@ Or in AI client configurations:
453
454
For more details, see the [official mcp-remote documentation](https://github.com/geelen/mcp-remote).
455
331
-## Finding Your API Key
456
+### Finding Your API Key
457
458
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.
459
@@ -336,7 +461,7 @@ You need the API key of the Netdata you will connect to (usually a Netdata Paren
461
462
**Note**: This temporary API key mechanism will eventually be replaced by integration with Netdata Cloud.
463
339
-### Find the API Key File
464
+#### Find the API Key File
465
466
```bash
467
# Try the default location first:
@@ -349,7 +474,7 @@ sudo cat /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key
474
sudo find / -name "mcp_dev_preview_api_key" 2>/dev/null
475
```
476
352
-### Copy the API Key
477
+#### Copy the API Key
478
479
The file contains a UUID that looks like:
480
@@ -359,7 +484,7 @@ a1b2c3d4-e5f6-7890-abcd-ef1234567890
484
485
Copy this entire string - you'll need it for your AI client configuration.
486
362
-### No API Key File?
487
+#### No API Key File?
488
489
If the file doesn't exist:
490
@@ -367,11 +492,11 @@ If the file doesn't exist:
492
2. Restart Netdata: `sudo systemctl restart netdata`
493
3. Check the file again after restart
494
370
-## AI Client Configuration
495
+### AI Client Configuration
496
497
AI clients can connect to Netdata MCP in different ways depending on their transport support:
498
374
-### Direct Connection (HTTP/SSE)
499
+#### Direct Connection (HTTP/SSE)
500
501
For AI clients that support HTTP or SSE transports:
502
@@ -405,7 +530,7 @@ Or for SSE:
530
}
531
```
532
408
-### Using nd-mcp Bridge (stdio)
533
+#### Using nd-mcp Bridge (stdio)
534
535
For AI clients that only support stdio:
536
@@ -424,7 +549,7 @@ For AI clients that only support stdio:
549
}
550
```
551
427
-### Using Official MCP Remote Client
552
+#### Using Official MCP Remote Client
553
554
```json
555
{
@@ -449,7 +574,7 @@ Replace:
574
- `YOUR_API_KEY`: The API key from the file mentioned above
575
- `/usr/sbin/nd-mcp`: With your actual nd-mcp path (if using the bridge)
576
452
-### Multiple MCP Servers
577
+#### Multiple MCP Servers
578
579
You can configure multiple Netdata instances:
580
@@ -468,11 +593,11 @@ You can configure multiple Netdata instances:
593
}
594
```
595
471
-### Legacy Query String Support
596
+#### Legacy Query String Support
597
598
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.
599
475
-## AI Client Specific Documentation
600
+### AI Client Specific Documentation
601
602
For detailed configuration instructions for specific AI clients, see:
603
docs/netdata-ai/mcp/ai-chat-netdata.md
+38
-26
@@ -4,7 +4,7 @@ Chat with your infrastructure using natural language through two distinct integr
4
5
## Integration Architecture
6
7
-### Method 1: Client-Controlled Communication (Available Now)
7
+### Method 1: Connect to a Local Agent or Parent
8
9
```mermaid
10
flowchart TB
@@ -61,34 +61,36 @@ flowchart TB
61
- No internet access required for Netdata Agent
62
- Full control over data flow and privacy
63
64
-### Method 2: LLM-Direct Communication (Coming Soon)
64
+### Method 2: Connect to Netdata Cloud
65
66
```mermaid
67
flowchart TB
68
LLM("LLM Provider<br/>OpenAI, Anthropic, etc.")
69
- CloudMCP("Netdata Cloud<br/>with MCP Server")
70
-
69
+ CloudMCP("Netdata Cloud MCP<br/>app.netdata.cloud/api/v1/mcp")
70
+
71
subgraph infra["Your Infrastructure"]
72
direction TB
73
subgraph userLayer[" "]
74
direction LR
75
User("User")
76
- Client("AI Client")
77
-
76
+ Client("AI Client<br/>Claude Desktop, Cursor, etc.")
77
+
78
User -->|"(1) Ask question"| Client
79
- Client -->|"(6) Display response"| User
79
+ Client -->|"(8) Display response"| User
80
end
81
-
81
+
82
Agents("Netdata Agents<br/>and Parents")
83
end
84
-
84
+
85
Client -->|"(2) Send query"| LLM
86
- LLM -.->|"(3) Access tools"| CloudMCP
87
- CloudMCP -.->|"(4) Return data"| LLM
88
- LLM -->|"(5) Final answer"| Client
89
-
90
- Agents -.-> CloudMCP
91
-
86
+ LLM -->|"(3) Tool commands"| Client
87
+ Client -->|"(4) Execute tools"| CloudMCP
88
+ CloudMCP -->|"(5) Return data"| Client
89
+ Client -->|"(6) Send results"| LLM
90
+ LLM -->|"(7) Final answer"| Client
91
+
92
+ Agents -.->|"Stream metrics"| CloudMCP
93
+
94
%% Style definitions
95
classDef alert fill:#ffeb3b,stroke:#000000,stroke-width:3px,color:#000000,font-size:18px
96
classDef neutral fill:#f9f9f9,stroke:#000000,stroke-width:3px,color:#000000,font-size:18px
@@ -106,23 +108,33 @@ flowchart TB
108
**How it works:**
109
110
1. You ask a question to your AI client
109
-2. LLM directly accesses Netdata Cloud MCP tools
110
-3. LLM provides the final answer with integrated data
111
+2. Your AI client sends the query to the LLM
112
+3. LLM responds with tool execution commands
113
+4. Your AI client executes tools against
114
+ Netdata Cloud MCP (over the internet)
115
+5. Netdata Cloud MCP returns the data
116
+6. Your AI client sends tool responses back to LLM
117
+7. LLM provides the final answer
118
+8. Your AI client displays the response
119
120
**Key characteristics:**
121
114
-- LLM provider manages MCP integration
115
-- Direct connection between LLM and MCP tools
116
-- Netdata Cloud MCP accessible via internet
117
-- Simplified setup, no local MCP configuration needed
122
+- Same client-controlled architecture as Method 1, but with a cloud-hosted MCP endpoint
123
+- No direct network access to Netdata Agents required
124
+- Complete visibility across all nodes in your infrastructure
125
+- Any MCP-aware client can connect
126
127
## Quick Comparison
128
121
-| Aspect | Method 1: Client-Controlled | Method 2: LLM-Direct |
129
+| Aspect | Method 1: Local Agent/Parent | Method 2: Netdata Cloud |
130
|--------|---------------------------|---------------------|
123
-| **Availability** | ✅ Available now | 🚧 Coming soon |
124
-| **Setup Complexity** | Moderate (configure AI client + MCP) | Simple (just AI client) |
131
+| **Setup Complexity** | Moderate (configure AI client + local MCP) | Simple (configure AI client + cloud endpoint) |
132
| **Data Privacy** | Depends on LLM provider | Depends on LLM provider |
133
| **Internet Requirements** | AI client needs internet, MCP is local | Both AI client and MCP need internet |
127
-| **Supported AI Clients** | Any MCP-aware client (including those using LLM APIs) | Only clients from providers that support MCP on LLM side |
128
-| **Infrastructure Access** | Limited to one Parent's scope | Complete visibility across all infrastructure |
134
+| **Supported AI Clients** | Any MCP-aware client | Any MCP-aware client |
135
+| **Infrastructure Access** | One Agent or Parent's scope | All infrastructure |
136
+| **Network Access** | Direct access to Netdata IP | No firewall changes |
137
+
138
+To get started with Method 2, see
139
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp)
140
+for setup instructions.
docs/netdata-ai/mcp/mcp-clients/claude-code.md
+54
-4
@@ -28,7 +28,57 @@ Claude Code has comprehensive MCP server management capabilities. For detailed d
28
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+)
31
+### Netdata Cloud MCP
32
+
33
+Connect to your entire Netdata Cloud infrastructure
34
+through a single endpoint — no local setup, bridges,
35
+or firewall changes needed.
36
+
37
+**Prerequisites:**
38
+
39
+- Netdata Cloud account with Business plan
40
+- Nodes claimed to Netdata Cloud
41
+- API token with `scope:mcp`
42
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
43
+
44
+```bash
45
+# Add for all your projects (user-scoped, personal)
46
+claude mcp add --transport http --scope user netdata-cloud \
47
+ https://app.netdata.cloud/api/v1/mcp \
48
+ --header "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
49
+
50
+# Or add for team sharing via version control (project-scoped)
51
+claude mcp add --transport http --scope project netdata-cloud \
52
+ https://app.netdata.cloud/api/v1/mcp \
53
+ --header "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
54
+```
55
+
56
+Or in `.mcp.json`:
57
+
58
+```json
59
+{
60
+ "mcpServers": {
61
+ "netdata-cloud": {
62
+ "type": "http",
63
+ "url": "https://app.netdata.cloud/api/v1/mcp",
64
+ "headers": {
65
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
66
+ }
67
+ }
68
+ }
69
+}
70
+```
71
+
72
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
73
+Netdata Cloud API token (must have `scope:mcp`).
74
+For more details, see
75
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
76
+
77
+### Local Agent or Parent
78
+
79
+The following methods connect directly to a Netdata Agent or Parent on your network.
80
+
81
+#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
82
83
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
84
@@ -49,7 +99,7 @@ claude mcp add --transport http --scope project netdata \
99
--header "Authorization: Bearer NETDATA_MCP_API_KEY"
100
```
101
52
-### Method 2: Using nd-mcp Bridge (stdio)
102
+#### Method 2: Using nd-mcp Bridge (stdio)
103
104
For environments where you prefer or need to use the bridge:
105
@@ -65,7 +115,7 @@ claude mcp add netdata /usr/sbin/nd-mcp \
115
ws://YOUR_NETDATA_IP:19999/mcp
116
```
117
68
-### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
118
+#### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
119
120
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/netdata-ai/mcp/README.md#using-mcp-remote-client).
121
@@ -83,7 +133,7 @@ claude mcp add --scope project netdata npx mcp-remote@latest \
133
--header "Authorization: Bearer NETDATA_MCP_API_KEY"
134
```
135
86
-### Verify Configuration
136
+#### Verify Configuration
137
138
```bash
139
# List configured servers
docs/netdata-ai/mcp/mcp-clients/claude-desktop.md
+44
-3
@@ -46,13 +46,54 @@ Use the community AppImage project:
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)
49
+### Netdata Cloud MCP
50
+
51
+Connect to your entire Netdata Cloud infrastructure
52
+through a single endpoint — no local Netdata setup
53
+or firewall changes needed.
54
+
55
+**Prerequisites:**
56
+
57
+- Netdata Cloud account with Business plan
58
+- Nodes claimed to Netdata Cloud
59
+- API token with `scope:mcp`
60
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
61
+
62
+Edit `claude_desktop_config.json` (see Method 2 below for file location):
63
+
64
+```json
65
+{
66
+ "mcpServers": {
67
+ "netdata-cloud": {
68
+ "command": "npx",
69
+ "args": [
70
+ "mcp-remote@latest",
71
+ "https://app.netdata.cloud/api/v1/mcp",
72
+ "--header",
73
+ "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
74
+ ]
75
+ }
76
+ }
77
+}
78
+```
79
+
80
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
81
+Netdata Cloud API token (must have `scope:mcp`).
82
+Restart Claude Desktop after saving.
83
+For more details, see
84
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
85
+
86
+### Local Agent or Parent
87
+
88
+The following methods connect directly to a Netdata Agent or Parent on your network.
89
+
90
+#### Method 1: Claude Desktop Custom Connectors (Anthropic-hosted beta)
91
92
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).
93
94
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.
95
55
-### Method 2: Traditional JSON Configuration with nd-mcp Bridge
96
+#### Method 2: Traditional JSON Configuration with nd-mcp Bridge
97
98
For all Netdata versions (v2.6.0+), you can manually configure MCP servers:
99
@@ -84,7 +125,7 @@ Add the Netdata configuration:
125
5. Save the configuration file
126
6. **Restart Claude Desktop** (required for changes to take effect)
127
87
-### Method 3: Traditional JSON Configuration with `npx mcp-remote` (v2.7.2+)
128
+#### Method 3: Traditional JSON Configuration with `npx mcp-remote` (v2.7.2+)
129
130
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.
131
docs/netdata-ai/mcp/mcp-clients/codex-cli.md
+38
-3
@@ -42,7 +42,42 @@ brew install codex
42
43
Codex CLI uses a TOML configuration file at `~/.codex/config.toml` for MCP server settings.
44
45
-### Method 1: Native Streamable HTTP (Recommended for v2.7.2+)
45
+### Netdata Cloud MCP
46
+
47
+Connect to your entire Netdata Cloud infrastructure
48
+through a single endpoint — no local setup, bridges,
49
+or firewall changes needed.
50
+
51
+**Prerequisites:**
52
+
53
+- Netdata Cloud account with Business plan
54
+- Nodes claimed to Netdata Cloud
55
+- API token with `scope:mcp`
56
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
57
+
58
+```toml
59
+# ~/.codex/config.toml
60
+
61
+[mcp_servers.netdata-cloud]
62
+url = "https://app.netdata.cloud/api/v1/mcp"
63
+bearer_token_env_var = "NETDATA_CLOUD_API_TOKEN"
64
+startup_timeout_sec = 20
65
+tool_timeout_sec = 120
66
+```
67
+
68
+Set the environment variable before starting Codex CLI:
69
+
70
+```bash
71
+export NETDATA_CLOUD_API_TOKEN="your-netdata-cloud-api-token"
72
+```
73
+
74
+The token must have `scope:mcp`. For more details, see [Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
75
+
76
+### Local Agent or Parent
77
+
78
+The following methods connect directly to a Netdata Agent or Parent on your network.
79
+
80
+#### Method 1: Native Streamable HTTP (Recommended for v2.7.2+)
81
82
Enable the RMCP client and point Codex directly at Netdata’s HTTP endpoint:
83
@@ -60,7 +95,7 @@ tool_timeout_sec = 120
95
96
> `bearer_token` is sent as `Authorization: Bearer <token>`. Consider sourcing it from an environment variable to avoid plain-text secrets.
97
63
-### Method 2: Using `npx mcp-remote` (Works for HTTP or SSE)
98
+#### Method 2: Using `npx mcp-remote` (Works for HTTP or SSE)
99
100
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/netdata-ai/mcp/README.md#using-mcp-remote-client).
101
@@ -96,7 +131,7 @@ args = [
131
]
132
```
133
99
-### Method 3: Using nd-mcp Bridge (WebSocket only)
134
+#### Method 3: Using nd-mcp Bridge (WebSocket only)
135
136
For environments where nd-mcp is available and preferred:
137
docs/netdata-ai/mcp/mcp-clients/crush.md
+43
-4
@@ -59,7 +59,46 @@ Crush uses JSON configuration files with the following priority:
59
2. `crush.json` (project-specific)
60
3. `~/.config/crush/crush.json` (global)
61
62
-### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
62
+### Netdata Cloud MCP
63
+
64
+Connect to your entire Netdata Cloud infrastructure
65
+through a single endpoint — no local setup, bridges,
66
+or firewall changes needed.
67
+
68
+**Prerequisites:**
69
+
70
+- Netdata Cloud account with Business plan
71
+- Nodes claimed to Netdata Cloud
72
+- API token with `scope:mcp`
73
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
74
+
75
+```json
76
+{
77
+ "$schema": "https://charm.land/crush.json",
78
+ "mcp": {
79
+ "netdata-cloud": {
80
+ "type": "http",
81
+ "url": "https://app.netdata.cloud/api/v1/mcp",
82
+ "headers": {
83
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
84
+ },
85
+ "timeout": 120,
86
+ "disabled": false
87
+ }
88
+ }
89
+}
90
+```
91
+
92
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
93
+Netdata Cloud API token (must have `scope:mcp`).
94
+For more details, see
95
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
96
+
97
+### Local Agent or Parent
98
+
99
+The following methods connect directly to a Netdata Agent or Parent on your network.
100
+
101
+#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
102
103
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
104
@@ -98,7 +137,7 @@ For HTTPS connections:
137
}
138
```
139
101
-### Method 2: Direct SSE Connection (v2.7.2+)
140
+#### Method 2: Direct SSE Connection (v2.7.2+)
141
142
Connect directly to Netdata's SSE endpoint for real-time streaming:
143
@@ -119,7 +158,7 @@ Connect directly to Netdata's SSE endpoint for real-time streaming:
158
}
159
```
160
122
-### Method 3: Using nd-mcp Bridge (stdio)
161
+#### Method 3: Using nd-mcp Bridge (stdio)
162
163
For environments where you prefer or need to use the bridge:
164
@@ -138,7 +177,7 @@ For environments where you prefer or need to use the bridge:
177
}
178
```
179
141
-### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
180
+#### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
181
182
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/netdata-ai/mcp/README.md#using-mcp-remote-client).
183
docs/netdata-ai/mcp/mcp-clients/cursor.md
+42
-3
@@ -30,7 +30,46 @@ Cursor’s MCP client natively supports multiple transports (https://cursor.com/
30
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
33
-### Method 1: stdio Bridge (All Netdata versions)
33
+### Netdata Cloud MCP
34
+
35
+Connect to your entire Netdata Cloud infrastructure
36
+through a single endpoint — no local setup, bridges,
37
+or firewall changes needed.
38
+
39
+**Prerequisites:**
40
+
41
+- Netdata Cloud account with Business plan
42
+- Nodes claimed to Netdata Cloud
43
+- API token with `scope:mcp`
44
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
45
+
46
+Add to `.cursor/mcp.json`:
47
+
48
+```json
49
+{
50
+ "mcpServers": {
51
+ "netdata-cloud": {
52
+ "type": "streamable-http",
53
+ "url": "https://app.netdata.cloud/api/v1/mcp",
54
+ "headers": {
55
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
56
+ }
57
+ }
58
+ }
59
+}
60
+```
61
+
62
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
63
+Netdata Cloud API token (must have `scope:mcp`).
64
+Restart Cursor or run "Reload Window" for the new
65
+server to appear. For more details, see
66
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
67
+
68
+### Local Agent or Parent
69
+
70
+The following methods connect directly to a Netdata Agent or Parent on your network.
71
+
72
+#### Method 1: stdio Bridge (All Netdata versions)
73
74
```json
75
{
@@ -46,7 +85,7 @@ Cursor reads MCP definitions from `.cursor/mcp.json` in the workspace root. For
85
}
86
```
87
49
-### Method 2: Direct SSE (Netdata v2.7.2+)
88
+#### Method 2: Direct SSE (Netdata v2.7.2+)
89
90
```json
91
{
@@ -62,7 +101,7 @@ Cursor reads MCP definitions from `.cursor/mcp.json` in the workspace root. For
101
}
102
```
103
65
-### Method 3: Streamable HTTP (Netdata v2.7.2+)
104
+#### Method 3: Streamable HTTP (Netdata v2.7.2+)
105
106
```json
107
{
docs/netdata-ai/mcp/mcp-clients/gemini-cli.md
+48
-4
@@ -39,7 +39,51 @@ 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
42
-### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
42
+### Netdata Cloud MCP
43
+
44
+Connect to your entire Netdata Cloud infrastructure
45
+through a single endpoint — no local setup, bridges,
46
+or firewall changes needed.
47
+
48
+**Prerequisites:**
49
+
50
+- Netdata Cloud account with Business plan
51
+- Nodes claimed to Netdata Cloud
52
+- API token with `scope:mcp`
53
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
54
+
55
+```bash
56
+# Using CLI command
57
+gemini mcp add --transport http netdata-cloud https://app.netdata.cloud/api/v1/mcp \
58
+ --header "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
59
+```
60
+
61
+Or configure in `~/.gemini/settings.json`:
62
+
63
+```json
64
+{
65
+ "mcpServers": {
66
+ "netdata-cloud": {
67
+ "httpUrl": "https://app.netdata.cloud/api/v1/mcp",
68
+ "headers": {
69
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
70
+ },
71
+ "timeout": 30000
72
+ }
73
+ }
74
+}
75
+```
76
+
77
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
78
+Netdata Cloud API token (must have `scope:mcp`).
79
+For more details, see
80
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
81
+
82
+### Local Agent or Parent
83
+
84
+The following methods connect directly to a Netdata Agent or Parent on your network.
85
+
86
+#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
87
88
Connect directly to Netdata's HTTP endpoint without needing any bridge:
89
@@ -69,7 +113,7 @@ Or configure in `~/.gemini/settings.json`:
113
}
114
```
115
72
-### Method 2: Direct SSE Connection (v2.7.2+)
116
+#### Method 2: Direct SSE Connection (v2.7.2+)
117
118
Connect directly to Netdata's SSE endpoint:
119
@@ -95,7 +139,7 @@ Or configure in `~/.gemini/settings.json`:
139
}
140
```
141
98
-### Method 3: Using nd-mcp Bridge (stdio)
142
+#### Method 3: Using nd-mcp Bridge (stdio)
143
144
For environments where you prefer or need to use the bridge:
145
@@ -123,7 +167,7 @@ Or configure in `~/.gemini/settings.json`:
167
}
168
```
169
126
-### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
170
+#### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
171
172
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/netdata-ai/mcp/README.md#using-mcp-remote-client).
173
docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md
+41
-2
@@ -56,7 +56,46 @@ JetBrains AI Assistant currently communicates with MCP servers over `stdio` only
56
MCP support in JetBrains IDEs may require additional plugins or configuration. Check the plugin documentation for the latest setup instructions.
57
:::
58
59
-### Method 1: Using nd-mcp Bridge (All Netdata versions v2.6.0+)
59
+### Netdata Cloud MCP
60
+
61
+Connect to your entire Netdata Cloud infrastructure
62
+through a single endpoint — no local Netdata setup
63
+or firewall changes needed.
64
+
65
+**Prerequisites:**
66
+
67
+- Netdata Cloud account with Business plan
68
+- Nodes claimed to Netdata Cloud
69
+- API token with `scope:mcp`
70
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
71
+
72
+Since JetBrains AI Assistant only supports stdio, use `npx mcp-remote` as a bridge:
73
+
74
+**AI Assistant Settings:**
75
+
76
+```json
77
+{
78
+ "name": "netdata-cloud",
79
+ "command": "npx",
80
+ "args": [
81
+ "mcp-remote@latest",
82
+ "https://app.netdata.cloud/api/v1/mcp",
83
+ "--header",
84
+ "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
85
+ ]
86
+}
87
+```
88
+
89
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
90
+Netdata Cloud API token (must have `scope:mcp`).
91
+For more details, see
92
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
93
+
94
+### Local Agent or Parent
95
+
96
+The following methods connect directly to a Netdata Agent or Parent on your network.
97
+
98
+#### Method 1: Using nd-mcp Bridge (All Netdata versions v2.6.0+)
99
100
**AI Assistant Settings:**
101
@@ -83,7 +122,7 @@ MCP support in JetBrains IDEs may require additional plugins or configuration. C
122
- **Program**: `/usr/sbin/nd-mcp`
123
- **Arguments**: `ws://YOUR_NETDATA_IP:19999/mcp`
124
86
-### Method 2: Using npx mcp-remote (Netdata v2.7.2+)
125
+#### Method 2: Using npx mcp-remote (Netdata v2.7.2+)
126
127
For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/netdata-ai/mcp/README.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.
128
docs/netdata-ai/mcp/mcp-clients/opencode.md
+41
-3
@@ -48,7 +48,45 @@ 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
51
-### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
51
+### Netdata Cloud MCP
52
+
53
+Connect to your entire Netdata Cloud infrastructure
54
+through a single endpoint — no local setup, bridges,
55
+or firewall changes needed.
56
+
57
+**Prerequisites:**
58
+
59
+- Netdata Cloud account with Business plan
60
+- Nodes claimed to Netdata Cloud
61
+- API token with `scope:mcp`
62
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
63
+
64
+```json
65
+{
66
+ "mcp": {
67
+ "netdata-cloud": {
68
+ "type": "remote",
69
+ "url": "https://app.netdata.cloud/api/v1/mcp",
70
+ "oauth": false,
71
+ "headers": {
72
+ "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
73
+ },
74
+ "enabled": true
75
+ }
76
+ }
77
+}
78
+```
79
+
80
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
81
+Netdata Cloud API token (must have `scope:mcp`).
82
+For more details, see
83
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
84
+
85
+### Local Agent or Parent
86
+
87
+The following methods connect directly to a Netdata Agent or Parent on your network.
88
+
89
+#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
90
91
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
92
@@ -84,7 +122,7 @@ For HTTPS connections:
122
}
123
```
124
87
-### Method 2: Using nd-mcp Bridge (Local)
125
+#### Method 2: Using nd-mcp Bridge (Local)
126
127
For environments where you prefer or need to use the bridge:
128
@@ -100,7 +138,7 @@ For environments where you prefer or need to use the bridge:
138
}
139
```
140
103
-### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)
141
+#### Method 3: 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/netdata-ai/mcp/README.md#using-mcp-remote-client).
144
docs/netdata-ai/mcp/mcp-clients/vs-code.md
+92
-18
@@ -42,9 +42,73 @@ VS Code extensions typically support stdio-based MCP servers:
42
```
43
Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key)
44
45
-## Continue Extension Setup
45
+## Netdata Cloud MCP
46
47
-### Installation
47
+Connect to your entire Netdata Cloud infrastructure
48
+through a single endpoint — no local setup, bridges,
49
+or firewall changes needed.
50
+
51
+**Prerequisites:**
52
+
53
+- Netdata Cloud account with Business plan
54
+- Nodes claimed to Netdata Cloud
55
+- API token with `scope:mcp`
56
+ ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))
57
+
58
+### Continue Extension
59
+
60
+Add to `.continue/mcpServers/netdata-cloud.yaml`:
61
+
62
+```yaml
63
+name: Netdata Cloud
64
+version: 0.0.1
65
+schema: v1
66
+mcpServers:
67
+ - name: netdata-cloud
68
+ type: streamable-http
69
+ url: https://app.netdata.cloud/api/v1/mcp
70
+ requestOptions:
71
+ headers:
72
+ Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN
73
+```
74
+
75
+### Cline Extension
76
+
77
+Cline only supports stdio and SSE transports.
78
+Since Netdata Cloud MCP uses Streamable HTTP,
79
+you need the `mcp-remote` bridge to convert
80
+stdio to HTTP:
81
+
82
+```json
83
+{
84
+ "mcpServers": {
85
+ "netdata-cloud": {
86
+ "command": "npx",
87
+ "args": [
88
+ "mcp-remote@latest",
89
+ "https://app.netdata.cloud/api/v1/mcp",
90
+ "--header",
91
+ "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
92
+ ],
93
+ "alwaysAllow": [],
94
+ "disabled": false
95
+ }
96
+ }
97
+}
98
+```
99
+
100
+Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
101
+Netdata Cloud API token (must have `scope:mcp`).
102
+For more details, see
103
+[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).
104
+
105
+## Local Agent or Parent
106
+
107
+The following methods connect directly to a Netdata Agent or Parent on your network.
108
+
109
+### Continue Extension
110
+
111
+#### Installation
112
113
1. Open VS Code
114
2. Go to Extensions (Ctrl+Shift+X)
@@ -52,9 +116,9 @@ VS Code extensions typically support stdio-based MCP servers:
116
4. Install the Continue extension
117
5. Reload VS Code
118
55
-### Configuration
119
+#### Configuration
120
57
-#### Step 1: Add Claude Model
121
+##### Step 1: Add Claude Model
122
123
1. Click "**Select model**" dropdown at the bottom (next to Chat dropdown)
124
2. Click "**+ Add Chat model**"
@@ -64,7 +128,7 @@ VS Code extensions typically support stdio-based MCP servers:
128
- **API key**: Enter your Anthropic API key
129
- Click "**Connect**"
130
67
-#### Step 2: Add Netdata MCP Server
131
+##### Step 2: Add Netdata MCP Server
132
133
Continue stores MCP definitions as YAML or JSON blocks. The recommended flow is:
134
@@ -72,7 +136,10 @@ Continue stores MCP definitions as YAML or JSON blocks. The recommended flow is:
136
2. Click "**+ Add MCP Servers**" to scaffold `.continue/mcpServers/<name>.yaml`
137
3. Replace the contents with one of the configurations below
138
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).
139
+> Continue's reference guide documents the `type`
140
+> field (`stdio`, `sse`, or `streamable-http`)
141
+> and block syntax
142
+> (https://docs.continue.dev/customize/deep-dives/mcp).
143
144
**Method 1: stdio launcher (all Netdata versions)**
145
@@ -100,8 +167,9 @@ mcpServers:
167
- name: netdata
168
type: sse
169
url: https://YOUR_NETDATA_IP:19999/mcp
103
- headers:
104
- Authorization: Bearer ${NETDATA_MCP_API_KEY}
170
+ requestOptions:
171
+ headers:
172
+ Authorization: Bearer ${NETDATA_MCP_API_KEY}
173
```
174
175
**Method 3: Streamable HTTP (Netdata v2.7.2+)**
@@ -114,13 +182,14 @@ mcpServers:
182
- name: netdata
183
type: streamable-http
184
url: https://YOUR_NETDATA_IP:19999/mcp
117
- headers:
118
- Authorization: Bearer ${NETDATA_MCP_API_KEY}
185
+ requestOptions:
186
+ headers:
187
+ Authorization: Bearer ${NETDATA_MCP_API_KEY}
188
```
189
190
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.
191
123
-### Usage
192
+#### Usage
193
194
Press `Ctrl+L` to open Continue chat, then:
195
@@ -130,21 +199,22 @@ Press `Ctrl+L` to open Continue chat, then:
199
@netdata are there any anomalies in the database servers?
200
```
201
133
-## Cline Extension Setup
202
+### Cline Extension
203
135
-### Installation
204
+#### Installation
205
206
1. Search for "Cline" in Extensions
207
2. Install and reload VS Code
208
140
-### Configuration
209
+#### Configuration
210
142
-Cline’s official docs describe two workflows (https://docs.cline.bot/mcp/configuring-mcp-servers):
211
+Cline's official docs describe two workflows
212
+(<https://docs.cline.bot/mcp/configuring-mcp-servers>):
213
214
- **UI configuration** – Click the MCP Servers icon → Configure tab → add/update servers, restart, toggle, and set timeouts.
215
- **JSON configuration** – Click **Configure MCP Servers** to open `cline_mcp_settings.json` and edit the underlying JSON.
216
147
-#### JSON examples
217
+##### JSON examples
218
219
**Stdio (`nd-mcp`)**
220
@@ -180,9 +250,13 @@ Cline’s official docs describe two workflows (https://docs.cline.bot/mcp/confi
250
}
251
```
252
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.
253
+> Optional fields such as `networkTimeout`,
254
+> `alwaysAllow`, and `env` map directly to
255
+> Cline's UI controls. SSE and stdio are the
256
+> two transports Cline supports today; pick
257
+> the one that matches your Netdata deployment.
258
185
-### Usage
259
+#### Usage
260
261
1. Open Cline (Ctrl+Shift+P → "Cline: Open Chat")
262
2. Cline can autonomously:
docs/netdata-cloud/authentication-and-authorization/api-tokens.md
+1
@@ -27,6 +27,7 @@ You can limit each token to specific scopes that define its access permissions:
27
| `scope:all` | Grants the same permissions as the user who created the token. Use case: Terraform provider integration. | Full access to all API endpoints |
28
| `scope:agent-ui` | Used by Agent for accessing the Cloud UI | Access to UI-related endpoints |
29
| `scope:grafana-plugin` | Used for the [Netdata Grafana plugin](https://github.com/netdata/netdata-grafana-datasource-plugin/blob/master/README.md) to access Netdata charts | Access to chart and data endpoints |
30
+| `scope:mcp` | Used to connect MCP clients (Claude Desktop, Cursor, etc.) to [Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp) for AI-assisted monitoring | Access to MCP server endpoints |
31
32
## API Versions
33