# OpenCode

Configure SST's OpenCode to access your Netdata infrastructure through MCP for terminal-based AI-powered DevOps operations.

## Transport Support

OpenCode supports both local and remote MCP servers:

| Transport | Support | Netdata Version | Use Case |
|-----------|---------|-----------------|----------|
| **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
| **Streamable HTTP** (remote) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
| **SSE** (Server-Sent Events) | ⚠️ Limited Support | v2.7.2+ | Known issues with SSE servers |
| **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP instead |

> **Note:** OpenCode has reported issues with SSE-based MCP servers ([GitHub Issue #834](https://github.com/sst/opencode/issues/834)). Use HTTP streamable transport for best compatibility.

## Prerequisites

1. **OpenCode installed** - Available via npm, brew, or direct download from [GitHub](https://github.com/sst/opencode)
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).
   - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
   - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP connections on v2.7.2+.
4. **Netdata MCP API key** - required when `[web].bearer token protection = yes`. When bearer protection is disabled, it is optional and unlocks sensitive observability data (protected functions, full access to logs). Each Netdata Agent or Parent has its own unique MCP API key - [Find your Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key)

> Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching OpenCode to keep secrets out of configuration files:
> ```bash
> export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
> ```

## Installation

Install OpenCode using one of these methods:

```bash
# Using npm (recommended)
npm i -g opencode-ai@latest

# Using Homebrew
brew install sst/tap/opencode

# Using curl installation script
curl -fsSL https://opencode.ai/install.sh | bash
```

## Configuration Methods

OpenCode uses an `opencode.json` configuration file with MCP servers defined under the `mcp` key.

### Netdata Cloud MCP

Connect to your entire Netdata Cloud infrastructure
through a single endpoint — no local setup, bridges,
or firewall changes needed.

**Prerequisites:**

- Netdata Cloud account with a Paid plan
- Nodes claimed to Netdata Cloud
- API token with `scope:mcp`
  ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))

```json
{
  "mcp": {
    "netdata-cloud": {
      "type": "remote",
      "url": "https://app.netdata.cloud/api/v1/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
      },
      "enabled": true
    }
  }
}
```

Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
Netdata Cloud API token (must have `scope:mcp`).
For more details, see
[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).

### Local Agent or Parent

The following methods connect directly to a Netdata Agent or Parent on your network.

#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)

Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:

```json
{
  "mcp": {
    "netdata": {
      "type": "remote",
      "url": "http://YOUR_NETDATA_IP:19999/mcp",
      "headers": {
        "Authorization": "Bearer NETDATA_MCP_API_KEY"
      },
      "enabled": true
    }
  }
}
```

For HTTPS connections:

```json
{
  "mcp": {
    "netdata": {
      "type": "remote",
      "url": "https://YOUR_NETDATA_IP:19999/mcp",
      "headers": {
        "Authorization": "Bearer NETDATA_MCP_API_KEY"
      },
      "enabled": true
    }
  }
}
```

#### Method 2: Using nd-mcp Bridge (Local)

For environments where you prefer or need to use the bridge:

```json
{
  "mcp": {
    "netdata": {
      "type": "local",
      "command": ["/usr/sbin/nd-mcp", "ws://YOUR_NETDATA_IP:19999/mcp"],
      "enabled": true
    }
  }
}
```

#### Method 3: Using npx mcp-remote (Alternative Bridge for v2.7.2+)

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).

```json
{
  "mcp": {
    "netdata": {
      "type": "local",
      "command": [
        "npx",
        "mcp-remote@latest",
        "--http",
        "http://YOUR_NETDATA_IP:19999/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer NETDATA_MCP_API_KEY"
      ],
      "enabled": true
    }
  }
}
```

## Environment Variables

OpenCode supports environment variables in local server configurations:

```json
{
  "mcp": {
    "netdata": {
      "type": "local",
      "command": ["/usr/sbin/nd-mcp", "ws://YOUR_NETDATA_IP:19999/mcp"],
      "enabled": true,
      "environment": {
        "ND_MCP_BEARER_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

For remote servers with environment variables:

```json
{
  "mcp": {
    "netdata": {
      "type": "remote",
      "url": "https://YOUR_NETDATA_IP:19999/mcp",
      "headers": {
        "Authorization": "Bearer ${NETDATA_API_KEY}"
      },
      "enabled": true
    }
  }
}
```

Replace in all examples:
- `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent
- `ND_MCP_BEARER_TOKEN` - Export with your [Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key) before launching OpenCode
- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge) (local method only)

## How to Use

Once configured, OpenCode can leverage Netdata's observability data through its terminal interface:

```bash
# Start OpenCode
opencode

# The AI assistant will have access to Netdata tools
# Ask infrastructure questions naturally:
What's the current CPU usage across all servers?
Show me any performance anomalies in the last hour
Which services are consuming the most resources?
```

## Selective Tool Enabling

OpenCode allows fine-grained control over MCP tool availability per agent:

```json
{
  "mcp": {
    "netdata": {
      "type": "remote",
      "url": "http://YOUR_NETDATA_IP:19999/mcp",
      "headers": {
        "Authorization": "Bearer NETDATA_MCP_API_KEY"
      },
      "enabled": true
    }
  },
  "tools": {
    "netdata*": false
  },
  "agent": {
    "infrastructure-analyst": {
      "tools": {
        "netdata*": true
      }
    }
  }
}
```

This configuration:
- Disables Netdata tools globally
- Enables them only for the "infrastructure-analyst" agent

## Example Workflows

**Performance Investigation:**
```
Investigate why our application response times increased this afternoon using Netdata metrics
```

**Resource Optimization:**
```
Check memory usage patterns across all nodes and suggest optimization strategies
```

**Alert Analysis:**
```
Explain the current active alerts from Netdata and their potential impact
```

**Anomaly Detection:**
```
Find any anomalous metrics in the last 2 hours and explain what might be causing them
```

> **💡 Advanced Usage:** OpenCode's terminal-based interface combined with Netdata observability creates powerful DevOps workflows. Learn about the opportunities and security considerations in [AI DevOps Copilot](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md).

## Troubleshooting

### MCP Server Not Connecting

- Verify Netdata is accessible: `curl http://YOUR_NETDATA_IP:19999/api/v3/info`
- Check the JSON syntax in your `opencode.json` file
- Ensure the MCP server is enabled (`"enabled": true`)

### SSE Transport Issues

OpenCode has known issues with SSE-based MCP servers. If you encounter "UnknownError Server error" messages:
- Switch to HTTP streamable transport (remove `?transport=sse` from URL)
- Use the local nd-mcp bridge instead
- Check [GitHub Issue #834](https://github.com/sst/opencode/issues/834) for updates

### Limited Data Access

- Verify API key is included in the connection URL or headers
- Check that the Netdata agent is properly configured for MCP
- Ensure MCP is enabled in your Netdata build

### Command Format Issues

- Local servers require command as an array: `["command", "arg1", "arg2"]`
- Remote servers use a URL string: `"url": "http://..."`
- Don't mix local and remote configuration options

## Advanced Configuration

### Multiple Environments

Configure different Netdata instances for different purposes:

```json
{
  "mcp": {
    "netdata-prod": {
      "type": "remote",
      "url": "https://prod-parent.company.com:19999/mcp",
      "headers": {
        "Authorization": "Bearer ${PROD_API_KEY}"
      },
      "enabled": true
    },
    "netdata-staging": {
      "type": "remote",
      "url": "https://staging-parent.company.com:19999/mcp",
      "headers": {
        "Authorization": "Bearer ${STAGING_API_KEY}"
      },
      "enabled": false
    },
    "netdata-local": {
      "type": "local",
      "command": ["/usr/sbin/nd-mcp", "ws://localhost:19999/mcp"],
      "environment": {
        "ND_MCP_BEARER_TOKEN": "${LOCAL_API_KEY}"
      },
      "enabled": true
    }
  }
}
```

### Debugging MCP Connections

Enable verbose logging to troubleshoot MCP issues:

```json
{
  "mcp": {
    "netdata": {
      "type": "remote",
      "url": "http://YOUR_NETDATA_IP:19999/mcp",
      "headers": {
        "Authorization": "Bearer NETDATA_MCP_API_KEY"
      },
      "enabled": true,
      "debug": true
    }
  }
}
```

## Documentation Links

- [OpenCode GitHub Repository](https://github.com/sst/opencode)
- [OpenCode Documentation](https://opencode.ai/docs)
- [OpenCode MCP Servers Guide](https://opencode.ai/docs/mcp-servers/)
- [SST Discord Community](https://discord.gg/sst)
- [Netdata MCP Setup](/docs/netdata-ai/mcp/README.md)
- [AI DevOps Best Practices](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md)
