| 1 | # Cursor |
| 2 | |
| 3 | Configure Cursor IDE to access your Netdata infrastructure through MCP. |
| 4 | |
| 5 | ## Transport Support |
| 6 | |
| 7 | Cursor’s MCP client natively supports multiple transports (https://cursor.com/docs/context/mcp): |
| 8 | |
| 9 | | Transport | Support | Netdata Version | Notes | |
| 10 | |-----------|---------|-----------------|-------| |
| 11 | | **stdio** | ✅ Fully Supported | v2.6.0+ | Launch Netdata via `nd-mcp` or `npx mcp-remote` | |
| 12 | | **SSE** | ✅ Fully Supported | v2.7.2+ | Configure `type: "sse"` with Netdata SSE endpoint | |
| 13 | | **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Configure `type: "streamable-http"` for Netdata HTTP endpoint | |
| 14 | | **WebSocket** | ❌ Not Supported | - | Use the stdio bridge for v2.6.0–v2.7.1 | |
| 15 | |
| 16 | ## Prerequisites |
| 17 | |
| 18 | 1. **Cursor installed** - Download from [cursor.com](https://www.cursor.com) |
| 19 | 2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999). |
| 20 | - **v2.6.0 - v2.7.1**: Only WebSocket transport is available, so launch Netdata through `nd-mcp` |
| 21 | - **v2.7.2+**: Expose Netdata over SSE or HTTP directly, or continue to use `nd-mcp` |
| 22 | 3. **Optional bridge** - `npx mcp-remote@latest` remains useful if you prefer stdio-only setups or want to re-use the same launcher for multiple clients. |
| 23 | 4. **Netdata MCP API key loaded into the environment** (recommended) - export it before launching Cursor: |
| 24 | ```bash |
| 25 | export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)" |
| 26 | ``` |
| 27 | Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key) |
| 28 | |
| 29 | ## Configuration Methods |
| 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 | ### 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 a Paid 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 | { |
| 76 | "mcpServers": { |
| 77 | "netdata": { |
| 78 | "type": "stdio", |
| 79 | "command": "/usr/sbin/nd-mcp", |
| 80 | "args": [ |
| 81 | "ws://YOUR_NETDATA_IP:19999/mcp" |
| 82 | ] |
| 83 | } |
| 84 | } |
| 85 | } |
| 86 | ``` |
| 87 | |
| 88 | #### Method 2: Direct SSE (Netdata v2.7.2+) |
| 89 | |
| 90 | ```json |
| 91 | { |
| 92 | "mcpServers": { |
| 93 | "netdata": { |
| 94 | "type": "sse", |
| 95 | "url": "https://YOUR_NETDATA_IP:19999/mcp", |
| 96 | "headers": { |
| 97 | "Authorization": "Bearer NETDATA_MCP_API_KEY" |
| 98 | } |
| 99 | } |
| 100 | } |
| 101 | } |
| 102 | ``` |
| 103 | |
| 104 | #### Method 3: Streamable HTTP (Netdata v2.7.2+) |
| 105 | |
| 106 | ```json |
| 107 | { |
| 108 | "mcpServers": { |
| 109 | "netdata": { |
| 110 | "type": "streamable-http", |
| 111 | "url": "https://YOUR_NETDATA_IP:19999/mcp", |
| 112 | "headers": { |
| 113 | "Authorization": "Bearer NETDATA_MCP_API_KEY" |
| 114 | } |
| 115 | } |
| 116 | } |
| 117 | } |
| 118 | ``` |
| 119 | |
| 120 | > Cursor supports config interpolation such as `${env:NETDATA_MCP_API_KEY}` or `${workspaceFolder}` inside `command`, `args`, `env`, `url`, and `headers` (https://cursor.com/docs/context/mcp#config-interpolation). Use these to avoid storing secrets in plain text. |
| 121 | |
| 122 | After editing `.cursor/mcp.json`, restart Cursor or run “Reload Window” for the new server to appear in **Settings → MCP**. |
| 123 | |
| 124 | ## Using Netdata in Cursor |
| 125 | |
| 126 | ### In Chat (Cmd+K) |
| 127 | |
| 128 | Reference Netdata directly in your queries: |
| 129 | |
| 130 | ``` |
| 131 | @netdata what's the current CPU usage? |
| 132 | @netdata show me database query performance |
| 133 | @netdata are there any anomalies in the web servers? |
| 134 | ``` |
| 135 | |
| 136 | ### In Code Comments |
| 137 | |
| 138 | Get infrastructure context while coding: |
| 139 | |
| 140 | ```python |
| 141 | # @netdata what's the typical memory usage of this service? |
| 142 | def process_large_dataset(): |
| 143 | # Implementation |
| 144 | ``` |
| 145 | |
| 146 | ### Multi-Model Support |
| 147 | |
| 148 | Cursor's strength is using multiple AI models. You can: |
| 149 | |
| 150 | - Use Claude for complex analysis |
| 151 | - Switch to GPT-4 for different perspectives |
| 152 | - Use smaller models for quick queries |
| 153 | |
| 154 | All models can access your Netdata data through MCP. |
| 155 | |
| 156 | ## Multiple Environments |
| 157 | |
| 158 | Cursor allows multiple MCP servers but requires manual toggling: |
| 159 | |
| 160 | ```json |
| 161 | { |
| 162 | "mcpServers": { |
| 163 | "netdata-prod": { |
| 164 | "type": "stdio", |
| 165 | "command": "/usr/sbin/nd-mcp", |
| 166 | "args": ["ws://prod-parent:19999/mcp"] |
| 167 | }, |
| 168 | "netdata-dev": { |
| 169 | "type": "stdio", |
| 170 | "command": "/usr/sbin/nd-mcp", |
| 171 | "args": ["ws://dev-parent:19999/mcp"] |
| 172 | } |
| 173 | } |
| 174 | } |
| 175 | ``` |
| 176 | |
| 177 | Use the toggle in settings to enable only the environment you need. |
| 178 | |
| 179 | > ℹ️ 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. |
| 180 | |
| 181 | ## Best Practices |
| 182 | |
| 183 | ### Infrastructure-Aware Development |
| 184 | |
| 185 | While coding, ask about: |
| 186 | |
| 187 | - Current resource usage of services you're modifying |
| 188 | - Historical performance patterns |
| 189 | - Impact of deployments on system metrics |
| 190 | |
| 191 | ### Debugging with Context |
| 192 | |
| 193 | ``` |
| 194 | @netdata show me the logs when this error last occurred |
| 195 | @netdata what was the system state during the last deployment? |
| 196 | @netdata find correlated metrics during the performance regression |
| 197 | ``` |
| 198 | |
| 199 | ### Performance Optimization |
| 200 | |
| 201 | ``` |
| 202 | @netdata analyze database query latency patterns |
| 203 | @netdata which endpoints have the highest response times? |
| 204 | @netdata show me resource usage trends for this service |
| 205 | ``` |
| 206 | |
| 207 | ## Troubleshooting |
| 208 | |
| 209 | ### MCP Server Not Available |
| 210 | |
| 211 | - Restart Cursor after adding configuration |
| 212 | - Verify JSON syntax in settings |
| 213 | - Check MCP is enabled in Cursor settings |
| 214 | |
| 215 | ### Connection Issues |
| 216 | |
| 217 | - Test Netdata accessibility: `curl http://YOUR_NETDATA_IP:19999/api/v3/info` |
| 218 | - Verify bridge path is correct and executable |
| 219 | - Check firewall allows connection to Netdata |
| 220 | |
| 221 | ### Multiple Servers Confusion |
| 222 | |
| 223 | - Cursor may query the wrong server if multiple are enabled |
| 224 | - Always disable unused servers |
| 225 | - Name servers clearly (prod, dev, staging) |
| 226 | |
| 227 | ### Limited Functionality |
| 228 | |
| 229 | - Ensure API key is included for full access |
| 230 | - Verify Netdata agent is claimed |
| 231 | - Check that required collectors are enabled |