| 1 | # Netdata MCP |
| 2 | |
| 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 | - **[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 | |
| 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 | - **Function Discovery** - Access to system functions including `processes`, `network-connections`, `streaming`, `systemd-journal`, `windows-events`, etc. |
| 17 | - **Alert Discovery** - Real-time visibility into active and raised alerts |
| 18 | - **Metrics Queries** - Complex aggregations and groupings with ML-powered anomaly detection |
| 19 | - **Metrics Scoring** - Root cause analysis leveraging anomaly detection and metric correlations |
| 20 | - **Alert History** - Complete alert transition logs and state changes |
| 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 | |
| 24 | AI assistants have different visibility depending on where they connect: |
| 25 | |
| 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 **Paid 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 | |
| 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 | #### Claude Code (One-Line Setup) |
| 86 | |
| 87 | If you're using [Claude Code](https://www.anthropic.com/claude-code), you can register the Netdata Cloud MCP server from any session with a single command — no JSON editing required: |
| 88 | |
| 89 | ```bash |
| 90 | claude mcp add --transport http --scope user netdata-cloud \ |
| 91 | https://app.netdata.cloud/api/v1/mcp \ |
| 92 | --header "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN" |
| 93 | ``` |
| 94 | |
| 95 | Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with a token that has `scope:mcp` — see [Creating an API Token](#creating-an-api-token) above, or go directly to **User Settings → API Tokens** in [Netdata Cloud](https://app.netdata.cloud). |
| 96 | |
| 97 | **Scope flags:** |
| 98 | |
| 99 | - `--scope user` — available in all your projects on this machine (recommended for personal use) |
| 100 | - `--scope local` — this project only, private to you (default when `--scope` is omitted) |
| 101 | - `--scope project` — this project, checked into `.mcp.json` and shared with your team (do **not** use with a raw token; reference an environment variable instead) |
| 102 | |
| 103 | **Useful companion commands:** |
| 104 | |
| 105 | ```bash |
| 106 | claude mcp list # show all configured servers and their connection status |
| 107 | claude mcp get netdata-cloud # show the configuration for this server |
| 108 | claude mcp remove netdata-cloud -s user # remove the server (match the scope you added with) |
| 109 | ``` |
| 110 | |
| 111 | Restart the Claude Code session after adding the server so the new tools load. |
| 112 | |
| 113 | For more Claude Code options — including connecting to a local Netdata Agent or Parent — see the [Claude Code guide](/docs/netdata-ai/mcp/mcp-clients/claude-code.md). |
| 114 | |
| 115 | #### Generic MCP Client (HTTP Transport) |
| 116 | |
| 117 | For any MCP client that supports Streamable HTTP transport: |
| 118 | |
| 119 | ```json |
| 120 | { |
| 121 | "mcpServers": { |
| 122 | "netdata-cloud": { |
| 123 | "type": "http", |
| 124 | "url": "https://app.netdata.cloud/api/v1/mcp", |
| 125 | "headers": { |
| 126 | "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN" |
| 127 | } |
| 128 | } |
| 129 | } |
| 130 | } |
| 131 | ``` |
| 132 | |
| 133 | #### Clients Requiring stdio Bridge |
| 134 | |
| 135 | For MCP clients that only support stdio transport, use `npx mcp-remote` as a bridge: |
| 136 | |
| 137 | ```json |
| 138 | { |
| 139 | "mcpServers": { |
| 140 | "netdata-cloud": { |
| 141 | "command": "npx", |
| 142 | "args": [ |
| 143 | "mcp-remote@latest", |
| 144 | "https://app.netdata.cloud/api/v1/mcp", |
| 145 | "--header", |
| 146 | "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN" |
| 147 | ] |
| 148 | } |
| 149 | } |
| 150 | } |
| 151 | ``` |
| 152 | |
| 153 | Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your |
| 154 | [API token](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md) |
| 155 | (must have `scope:mcp`). |
| 156 | |
| 157 | ### Cloud MCP Troubleshooting |
| 158 | |
| 159 | #### Authentication Errors |
| 160 | |
| 161 | - Verify your API token has `scope:mcp` |
| 162 | - Ensure the token is passed as `Authorization: Bearer <token>` (not as a query parameter) |
| 163 | - Check that your Netdata Cloud subscription |
| 164 | includes a space in a Paid plan |
| 165 | |
| 166 | #### No Nodes Visible |
| 167 | |
| 168 | - Confirm your nodes are claimed to Netdata Cloud and appear in the web dashboard |
| 169 | - Check that agents are online and streaming to Cloud |
| 170 | |
| 171 | #### Connection Issues |
| 172 | |
| 173 | - The endpoint uses HTTPS — no `--allow-http` flag is needed |
| 174 | - Test connectivity: `curl -H "Authorization: Bearer YOUR_TOKEN" https://app.netdata.cloud/api/v1/mcp` |
| 175 | |
| 176 | ## Local Agent or Parent MCP |
| 177 | |
| 178 | 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`. |
| 179 | |
| 180 | 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. |
| 181 | |
| 182 | ### Transport Options |
| 183 | |
| 184 | Netdata implements the MCP protocol with multiple transport options: |
| 185 | |
| 186 | | Transport | Endpoint | Use Case | Version Requirement | |
| 187 | |---------------------|----------------------------|--------------------------------------------------------------|----------------------| |
| 188 | | **WebSocket** | `ws://YOUR_IP:19999/mcp` | Original transport, requires nd-mcp bridge for stdio clients | v2.6.0+ | |
| 189 | | **HTTP Streamable** | `http://YOUR_IP:19999/mcp` | Direct connection from AI clients supporting HTTP | v2.7.2+ | |
| 190 | | **SSE** | `http://YOUR_IP:19999/sse` | Server-Sent Events for real-time streaming | v2.7.2+ | |
| 191 | |
| 192 | - **Direct Connection** (v2.7.2+): AI clients that support HTTP or SSE transports can connect directly to Netdata |
| 193 | - **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 |
| 194 | |
| 195 | #### Official MCP Remote Client (mcp-remote) |
| 196 | |
| 197 | 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+): |
| 198 | |
| 199 | ```bash |
| 200 | # Export your MCP key once per shell |
| 201 | export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)" |
| 202 | |
| 203 | # For HTTP transport |
| 204 | npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \ |
| 205 | --allow-http \ |
| 206 | --header "Authorization: Bearer $NETDATA_MCP_API_KEY" |
| 207 | |
| 208 | # For SSE transport |
| 209 | npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \ |
| 210 | --allow-http \ |
| 211 | --header "Authorization: Bearer $NETDATA_MCP_API_KEY" |
| 212 | ``` |
| 213 | |
| 214 | **Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted. |
| 215 | |
| 216 | ### Finding the nd-mcp Bridge |
| 217 | |
| 218 | > **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. |
| 219 | |
| 220 | The nd-mcp bridge is only needed for AI clients that: |
| 221 | - Only support `stdio` communication (like some desktop applications) |
| 222 | - Cannot use HTTP or SSE transports directly |
| 223 | - Cannot use `npx mcp-remote@latest` |
| 224 | |
| 225 | 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: |
| 226 | |
| 227 | 1. **If you have Netdata installed locally** - Use the existing nd-mcp |
| 228 | 2. **If Netdata is only on remote servers** - Build nd-mcp on your desktop/laptop |
| 229 | |
| 230 | #### Option 1: Using Existing nd-mcp |
| 231 | |
| 232 | If you have Netdata installed on your desktop/laptop, find the existing bridge: |
| 233 | |
| 234 | ##### Linux |
| 235 | |
| 236 | ```bash |
| 237 | # Try these locations in order: |
| 238 | which nd-mcp |
| 239 | ls -la /usr/sbin/nd-mcp |
| 240 | ls -la /usr/bin/nd-mcp |
| 241 | ls -la /opt/netdata/usr/bin/nd-mcp |
| 242 | ls -la /usr/local/bin/nd-mcp |
| 243 | ls -la /usr/local/netdata/usr/bin/nd-mcp |
| 244 | |
| 245 | # Or search for it: |
| 246 | find / -name "nd-mcp" 2>/dev/null |
| 247 | ``` |
| 248 | |
| 249 | Common locations: |
| 250 | |
| 251 | - **Native packages (apt, yum, etc.)**: `/usr/sbin/nd-mcp` or `/usr/bin/nd-mcp` |
| 252 | - **Static installations**: `/opt/netdata/usr/bin/nd-mcp` |
| 253 | - **Built from source**: `/usr/local/netdata/usr/bin/nd-mcp` |
| 254 | |
| 255 | ##### macOS |
| 256 | |
| 257 | ```bash |
| 258 | # Try these locations: |
| 259 | which nd-mcp |
| 260 | ls -la /usr/local/bin/nd-mcp |
| 261 | ls -la /usr/local/netdata/usr/bin/nd-mcp |
| 262 | ls -la /opt/homebrew/bin/nd-mcp |
| 263 | |
| 264 | # Or search for it: |
| 265 | find / -name "nd-mcp" 2>/dev/null |
| 266 | ``` |
| 267 | |
| 268 | ##### Windows |
| 269 | |
| 270 | ```powershell |
| 271 | # Check common locations: |
| 272 | dir "C:\Program Files\Netdata\usr\bin\nd-mcp.exe" |
| 273 | dir "C:\Netdata\usr\bin\nd-mcp.exe" |
| 274 | # Or search for it: |
| 275 | where nd-mcp.exe |
| 276 | ``` |
| 277 | |
| 278 | #### Option 2: Building nd-mcp for Your Desktop |
| 279 | |
| 280 | 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: |
| 281 | |
| 282 | 1. **Go bridge** (recommended) - [Go bridge source code](https://github.com/netdata/netdata/tree/master/src/web/mcp/bridges/stdio-golang) |
| 283 | - Produces a single binary with no dependencies |
| 284 | - Creates executable named `nd-mcp` (`nd-mcp.exe` on windows) |
| 285 | - Includes both `build.sh` and `build.bat` (for Windows) |
| 286 | |
| 287 | 2. **Node.js bridge** - [Node.js bridge source code](https://github.com/netdata/netdata/tree/master/src/web/mcp/bridges/stdio-nodejs) |
| 288 | - Good if you already have Node.js installed |
| 289 | - Creates script named `nd-mcp.js` |
| 290 | - Includes `build.sh` |
| 291 | |
| 292 | 3. **Python bridge** - [Python bridge source code](https://github.com/netdata/netdata/tree/master/src/web/mcp/bridges/stdio-python) |
| 293 | - Good if you already have Python installed |
| 294 | - Creates script named `nd-mcp.py` |
| 295 | - Includes `build.sh` |
| 296 | |
| 297 | To build: |
| 298 | |
| 299 | ```bash |
| 300 | # Clone the Netdata repository |
| 301 | git clone https://github.com/netdata/netdata.git |
| 302 | cd netdata |
| 303 | |
| 304 | # Choose your preferred implementation |
| 305 | cd src/web/mcp/bridges/stdio-golang/ # or stdio-nodejs/ or stdio-python/ |
| 306 | |
| 307 | # Build the bridge |
| 308 | ./build.sh # On Windows with the Go version, use build.bat |
| 309 | |
| 310 | # The executable will be created with different names: |
| 311 | # - Go: nd-mcp |
| 312 | # - Node.js: nd-mcp.js |
| 313 | # - Python: nd-mcp.py |
| 314 | |
| 315 | # Test the bridge with your Netdata instance (replace localhost with your Netdata IP) |
| 316 | ./nd-mcp ws://localhost:19999/mcp # Go bridge |
| 317 | ./nd-mcp.js ws://localhost:19999/mcp # Node.js bridge |
| 318 | ./nd-mcp.py ws://localhost:19999/mcp # Python bridge |
| 319 | |
| 320 | # You should see: |
| 321 | # nd-mcp: Connecting to ws://localhost:19999/mcp... |
| 322 | # nd-mcp: Connected |
| 323 | # Press Ctrl+C to stop the test |
| 324 | |
| 325 | # Get the absolute path for your AI client configuration |
| 326 | pwd # Shows current directory |
| 327 | # Example output: /home/user/netdata/src/web/mcp/bridges/stdio-golang |
| 328 | # Your nd-mcp path would be: /home/user/netdata/src/web/mcp/bridges/stdio-golang/nd-mcp |
| 329 | ``` |
| 330 | |
| 331 | **Important**: When configuring your AI client, use the full absolute path to the executable: |
| 332 | |
| 333 | - Go bridge: `/path/to/bridges/stdio-golang/nd-mcp` |
| 334 | - Node.js bridge: `/path/to/bridges/stdio-nodejs/nd-mcp.js` |
| 335 | - Python bridge: `/path/to/bridges/stdio-python/nd-mcp.py` |
| 336 | |
| 337 | #### Verify the Bridge Works |
| 338 | |
| 339 | Once you have nd-mcp (either from existing installation or built), test it: |
| 340 | |
| 341 | ```bash |
| 342 | # Test connection to your Netdata instance (replace YOUR_NETDATA_IP with actual IP) |
| 343 | /path/to/nd-mcp ws://YOUR_NETDATA_IP:19999/mcp |
| 344 | |
| 345 | # You should see: |
| 346 | # nd-mcp: Connecting to ws://YOUR_NETDATA_IP:19999/mcp... |
| 347 | # nd-mcp: Connected |
| 348 | # Press Ctrl+C to stop the test |
| 349 | ``` |
| 350 | |
| 351 | ### Using MCP Remote Client |
| 352 | |
| 353 | 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. |
| 354 | |
| 355 | #### When to Use MCP Remote |
| 356 | |
| 357 | Use `mcp-remote` when: |
| 358 | - Your AI client only supports stdio communication |
| 359 | - You want to use HTTP or SSE transports instead of WebSocket |
| 360 | - You're running Netdata v2.7.2 or later |
| 361 | - You don't want to build/install nd-mcp |
| 362 | |
| 363 | #### Installation |
| 364 | |
| 365 | No installation required - `mcp-remote` runs via `npx`: |
| 366 | |
| 367 | ```bash |
| 368 | # Test the connection |
| 369 | npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \ |
| 370 | --allow-http \ |
| 371 | --header "Authorization: Bearer YOUR_API_KEY" |
| 372 | ``` |
| 373 | |
| 374 | #### Transport Options |
| 375 | |
| 376 | `mcp-remote` supports multiple transport strategies: |
| 377 | |
| 378 | ```bash |
| 379 | # HTTP transport (recommended) |
| 380 | npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \ |
| 381 | --allow-http \ |
| 382 | --header "Authorization: Bearer YOUR_API_KEY" |
| 383 | |
| 384 | # SSE transport |
| 385 | npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \ |
| 386 | --allow-http \ |
| 387 | --header "Authorization: Bearer YOUR_API_KEY" |
| 388 | |
| 389 | # Auto-detect with fallback (tries SSE first, falls back to HTTP) |
| 390 | npx mcp-remote@latest --transport sse-first http://YOUR_NETDATA_IP:19999/mcp \ |
| 391 | --allow-http \ |
| 392 | --header "Authorization: Bearer YOUR_API_KEY" |
| 393 | |
| 394 | # HTTPS (no --allow-http flag needed) |
| 395 | npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \ |
| 396 | --header "Authorization: Bearer YOUR_API_KEY" |
| 397 | ``` |
| 398 | |
| 399 | #### Common Options |
| 400 | |
| 401 | | Option | Description | Example | |
| 402 | |----------------|------------------------------------------------------|---------------------------------------------------------| |
| 403 | | `--http` | Use HTTP transport | `--http http://host:19999/mcp` | |
| 404 | | `--sse` | Use SSE transport | `--sse http://host:19999/mcp` | |
| 405 | | `--allow-http` | Allow non-HTTPS connections (required for HTTP URLs) | `--allow-http` | |
| 406 | | `--header` | Add custom headers (for authentication) | `--header "Authorization: Bearer KEY"` | |
| 407 | | `--transport` | Transport strategy | `--transport sse-first` (tries SSE, falls back to HTTP) | |
| 408 | | `--debug` | Enable debug logging | `--debug` | |
| 409 | | `--host` | OAuth callback host (default: localhost) | `--host 127.0.0.1` | |
| 410 | | Port number | OAuth callback port (optional) | `9696` | |
| 411 | |
| 412 | #### Authentication |
| 413 | |
| 414 | For Netdata MCP, pass the API key via the Authorization header: |
| 415 | |
| 416 | ```bash |
| 417 | # Using environment variable (recommended) |
| 418 | export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)" |
| 419 | |
| 420 | npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \ |
| 421 | --allow-http \ |
| 422 | --header "Authorization: Bearer $NETDATA_MCP_API_KEY" |
| 423 | ``` |
| 424 | |
| 425 | **Security Note:** The `--allow-http` flag is required for non-HTTPS connections. Only use this on trusted networks as traffic will not be encrypted. |
| 426 | |
| 427 | #### Troubleshooting |
| 428 | |
| 429 | **Connection Issues:** |
| 430 | ```bash |
| 431 | # Enable debug logging |
| 432 | npx mcp-remote@latest --debug --http http://YOUR_NETDATA_IP:19999/mcp \ |
| 433 | --allow-http \ |
| 434 | --header "Authorization: Bearer YOUR_API_KEY" |
| 435 | |
| 436 | # Check debug logs (stored in ~/.mcp-auth/) |
| 437 | cat ~/.mcp-auth/*_debug.log |
| 438 | ``` |
| 439 | |
| 440 | **Clear Authentication State:** |
| 441 | ```bash |
| 442 | # Remove cached credentials |
| 443 | rm -rf ~/.mcp-auth |
| 444 | ``` |
| 445 | |
| 446 | **Spaces in Arguments:** |
| 447 | |
| 448 | Some AI clients (Cursor, Claude Desktop on Windows) have issues with spaces in arguments. Use environment variables as a workaround: |
| 449 | |
| 450 | ```json |
| 451 | { |
| 452 | "mcpServers": { |
| 453 | "netdata": { |
| 454 | "command": "npx", |
| 455 | "args": [ |
| 456 | "mcp-remote@latest", |
| 457 | "--http", |
| 458 | "http://YOUR_IP:19999/mcp", |
| 459 | "--allow-http", |
| 460 | "--header", |
| 461 | "Authorization: Bearer YOUR_API_KEY" |
| 462 | ] |
| 463 | } |
| 464 | } |
| 465 | } |
| 466 | ``` |
| 467 | |
| 468 | #### Version Management |
| 469 | |
| 470 | Always use the latest version: |
| 471 | |
| 472 | ```bash |
| 473 | # Force npx to check for latest version |
| 474 | npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp |
| 475 | ``` |
| 476 | |
| 477 | Or in AI client configurations: |
| 478 | ```json |
| 479 | { |
| 480 | "args": ["mcp-remote@latest", "--http", "..."] |
| 481 | } |
| 482 | ``` |
| 483 | |
| 484 | For more details, see the [official mcp-remote documentation](https://github.com/geelen/mcp-remote). |
| 485 | |
| 486 | ### Finding Your API Key |
| 487 | |
| 488 | 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. |
| 489 | |
| 490 | You need the API key of the Netdata you will connect to (usually a Netdata Parent). |
| 491 | |
| 492 | **Note**: This temporary API key mechanism will eventually be replaced by integration with Netdata Cloud. |
| 493 | |
| 494 | #### Find the API Key File |
| 495 | |
| 496 | ```bash |
| 497 | # Try the default location first: |
| 498 | sudo cat /var/lib/netdata/mcp_dev_preview_api_key |
| 499 | |
| 500 | # For static installations: |
| 501 | sudo cat /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key |
| 502 | |
| 503 | # If not found, search for it: |
| 504 | sudo find / -name "mcp_dev_preview_api_key" 2>/dev/null |
| 505 | ``` |
| 506 | |
| 507 | #### Copy the API Key |
| 508 | |
| 509 | The file contains a UUID that looks like: |
| 510 | |
| 511 | ``` |
| 512 | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| 513 | ``` |
| 514 | |
| 515 | Copy this entire string - you'll need it for your AI client configuration. |
| 516 | |
| 517 | #### No API Key File? |
| 518 | |
| 519 | If the file doesn't exist: |
| 520 | |
| 521 | 1. Ensure you have a recent version of Netdata |
| 522 | 2. Restart Netdata: `sudo systemctl restart netdata` |
| 523 | 3. Check the file again after restart |
| 524 | |
| 525 | ### AI Client Configuration |
| 526 | |
| 527 | AI clients can connect to Netdata MCP in different ways depending on their transport support: |
| 528 | |
| 529 | #### Direct Connection (HTTP/SSE) |
| 530 | |
| 531 | For AI clients that support HTTP or SSE transports: |
| 532 | |
| 533 | ```json |
| 534 | { |
| 535 | "mcpServers": { |
| 536 | "netdata": { |
| 537 | "type": "http", |
| 538 | "url": "http://IP_OF_YOUR_NETDATA:19999/mcp", |
| 539 | "headers": [ |
| 540 | "Authorization: Bearer YOUR_API_KEY" |
| 541 | ] |
| 542 | } |
| 543 | } |
| 544 | } |
| 545 | ``` |
| 546 | |
| 547 | Or for SSE: |
| 548 | |
| 549 | ```json |
| 550 | { |
| 551 | "mcpServers": { |
| 552 | "netdata": { |
| 553 | "type": "sse", |
| 554 | "url": "http://IP_OF_YOUR_NETDATA:19999/mcp?transport=sse", |
| 555 | "headers": [ |
| 556 | "Authorization: Bearer YOUR_API_KEY" |
| 557 | ] |
| 558 | } |
| 559 | } |
| 560 | } |
| 561 | ``` |
| 562 | |
| 563 | #### Using nd-mcp Bridge (stdio) |
| 564 | |
| 565 | For AI clients that only support stdio: |
| 566 | |
| 567 | ```json |
| 568 | { |
| 569 | "mcpServers": { |
| 570 | "netdata": { |
| 571 | "command": "/usr/sbin/nd-mcp", |
| 572 | "args": [ |
| 573 | "--bearer", |
| 574 | "YOUR_API_KEY", |
| 575 | "ws://IP_OF_YOUR_NETDATA:19999/mcp" |
| 576 | ] |
| 577 | } |
| 578 | } |
| 579 | } |
| 580 | ``` |
| 581 | |
| 582 | #### Using Official MCP Remote Client |
| 583 | |
| 584 | ```json |
| 585 | { |
| 586 | "mcpServers": { |
| 587 | "netdata": { |
| 588 | "command": "npx", |
| 589 | "args": [ |
| 590 | "mcp-remote@latest", |
| 591 | "--http", |
| 592 | "http://IP_OF_YOUR_NETDATA:19999/mcp", |
| 593 | "--header", |
| 594 | "Authorization: Bearer YOUR_API_KEY" |
| 595 | ] |
| 596 | } |
| 597 | } |
| 598 | } |
| 599 | ``` |
| 600 | |
| 601 | Replace: |
| 602 | |
| 603 | - `IP_OF_YOUR_NETDATA`: Your Netdata instance IP/hostname |
| 604 | - `YOUR_API_KEY`: The API key from the file mentioned above |
| 605 | - `/usr/sbin/nd-mcp`: With your actual nd-mcp path (if using the bridge) |
| 606 | |
| 607 | #### Multiple MCP Servers |
| 608 | |
| 609 | You can configure multiple Netdata instances: |
| 610 | |
| 611 | ```json |
| 612 | { |
| 613 | "mcpServers": { |
| 614 | "netdata-production": { |
| 615 | "command": "/usr/sbin/nd-mcp", |
| 616 | "args": ["--bearer", "PROD_KEY", "ws://prod-parent:19999/mcp"] |
| 617 | }, |
| 618 | "netdata-testing": { |
| 619 | "command": "/usr/sbin/nd-mcp", |
| 620 | "args": ["--bearer", "TEST_KEY", "ws://test-parent:19999/mcp"] |
| 621 | } |
| 622 | } |
| 623 | } |
| 624 | ``` |
| 625 | |
| 626 | #### Legacy Query String Support |
| 627 | |
| 628 | 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. |
| 629 | |
| 630 | ### AI Client Specific Documentation |
| 631 | |
| 632 | For detailed configuration instructions for specific AI clients, see: |
| 633 | |
| 634 | **Chat Clients:** |
| 635 | - [Claude Desktop](/docs/netdata-ai/mcp/mcp-clients/claude-desktop.md) - Anthropic's desktop AI assistant |
| 636 | - [Cursor](/docs/netdata-ai/mcp/mcp-clients/cursor.md) - AI-powered code editor |
| 637 | - [Visual Studio Code](/docs/netdata-ai/mcp/mcp-clients/vs-code.md) - VS Code with MCP support |
| 638 | - [JetBrains IDEs](/docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md) - IntelliJ, PyCharm, WebStorm, etc. |
| 639 | |
| 640 | **DevOps Copilots:** |
| 641 | - [Claude Code](/docs/netdata-ai/mcp/mcp-clients/claude-code.md) - Anthropic's CLI for Claude |
| 642 | - [Gemini CLI](/docs/netdata-ai/mcp/mcp-clients/gemini-cli.md) - Google's Gemini CLI |
| 643 | - [OpenAI Codex CLI](/docs/netdata-ai/mcp/mcp-clients/codex-cli.md) - OpenAI's Codex CLI |
| 644 | - [Crush](/docs/netdata-ai/mcp/mcp-clients/crush.md) - Charmbracelet's glamorous terminal AI |
| 645 | - [OpenCode](/docs/netdata-ai/mcp/mcp-clients/opencode.md) - SST's terminal-based AI assistant |
| 646 | |
| 647 | Each guide includes specific transport support matrices and configuration examples optimized for that client. |