OpenAI Codex CLI

Configure OpenAI's Codex CLI to access your Netdata infrastructure through MCP for AI-powered DevOps operations.

Transport Support

Codex CLI supports both stdio launchers and direct Streamable HTTP when the RMCP client is enabled (https://github.com/openai/codex/blob/main/docs/config.md#mcp-servers).

Prerequisites

1. OpenAI Codex CLI installed - Available via npm, Homebrew, or direct download from GitHub
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+: Can use npx mcp-remote bridge for HTTP/SSE support
3. Launcher – Run Netdata through nd-mcp (always) or npx mcp-remote (useful when you want a single stdio launcher for multiple MCP clients). Direct HTTP is also available for v2.7.2+ when you enable the RMCP client.
4. Optionally, the Netdata MCP API key that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. Each Netdata Agent or Parent has its own unique API key for MCP - Find your Netdata MCP API key

Installation

Install Codex CLI using one of these methods:

# Using npm (recommended)
npm install -g @openai/codex

# Using Homebrew (macOS)
brew install codex

# Or download directly from GitHub releases
# https://github.com/openai/codex/releases

Configuration Methods

Codex CLI uses a TOML configuration file at ~/.codex/config.toml for MCP server settings.

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 Business plan
• Nodes claimed to Netdata Cloud
• API token with scope:mcp (create one)

# ~/.codex/config.toml

[mcp_servers.netdata-cloud]
url = "https://app.netdata.cloud/api/v1/mcp"
bearer_token_env_var = "NETDATA_CLOUD_API_TOKEN"
startup_timeout_sec = 20
tool_timeout_sec = 120

Set the environment variable before starting Codex CLI:

export NETDATA_CLOUD_API_TOKEN="your-netdata-cloud-api-token"

The token must have scope:mcp. For more details, see Netdata Cloud MCP.

Local Agent or Parent

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

Method 1: Native Streamable HTTP (Recommended for v2.7.2+)

Enable the RMCP client and point Codex directly at Netdata’s HTTP endpoint:

# ~/.codex/config.toml

experimental_use_rmcp_client = true

[mcp_servers.netdata]
url = "https://YOUR_NETDATA_IP:19999/mcp"
bearer_token = "${NETDATA_MCP_API_KEY}"
startup_timeout_sec = 20
tool_timeout_sec = 120

bearer_token is sent as Authorization: Bearer <token>. Consider sourcing it from an environment variable to avoid plain-text secrets.

Method 2: Using npx mcp-remote (Works for HTTP or SSE)

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.

# ~/.codex/config.toml

[mcp_servers.netdata]
command = "npx"
args = [
  "mcp-remote@latest",
  "--http",
  "--allow-http",
  "http://YOUR_NETDATA_IP:19999/mcp",
  "--header",
  "Authorization: Bearer NETDATA_MCP_API_KEY"
]
startup_timeout_sec = 20  # Optional: increase for remote connections
tool_timeout_sec = 120     # Optional: increase for complex queries

For SSE transport instead of HTTP:

[mcp_servers.netdata]
command = "npx"
args = [
  "mcp-remote@latest",
  "--sse",
  "http://YOUR_NETDATA_IP:19999/mcp",
  "--allow-http",
  "--header",
  "Authorization: Bearer NETDATA_MCP_API_KEY",
]

Method 3: Using nd-mcp Bridge (WebSocket only)

For environments where nd-mcp is available and preferred:

# ~/.codex/config.toml

[mcp_servers.netdata]
command = "/usr/sbin/nd-mcp"
args = ["ws://YOUR_NETDATA_IP:19999/mcp"]
env = { "ND_MCP_BEARER_TOKEN" = "YOUR_API_KEY_HERE" }
startup_timeout_sec = 15
tool_timeout_sec = 60

[mcp_servers.netdata_prod]
command = "/usr/sbin/nd-mcp"
args = ["ws://prod-parent:19999/mcp"]
env = { "ND_MCP_BEARER_TOKEN" = "${NETDATA_PROD_API_KEY}" }

Export ND_MCP_BEARER_TOKEN before starting Codex CLI (or define it in your shell profile) so the bridge authenticates without exposing the key in command-line arguments.

When Codex CLI starts the bridge it will inject the environment variable, so nd-mcp authenticates without exposing the token in the connection arguments.

CLI Management (Experimental)

Codex CLI provides experimental commands for managing MCP servers:

# Add a new MCP server
codex mcp add netdata -- npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer NETDATA_MCP_API_KEY"

# List configured MCP servers
codex mcp list

# Remove an MCP server
codex mcp remove netdata

Verify Configuration

After configuring, verify that Netdata MCP is available:

1. Start Codex CLI:

   bashCopy

   codex
   

2. Check available tools (if MCP is properly configured, Netdata tools should be available)

Replace in all examples:

• YOUR_NETDATA_IP - IP address or hostname of your Netdata Agent/Parent
• NETDATA_MCP_API_KEY - Your Netdata MCP API key
• /usr/sbin/nd-mcp - With your actual nd-mcp path (nd-mcp method only)

How to Use

Once configured, Codex CLI can leverage Netdata's observability data for infrastructure analysis:

# Start Codex CLI
codex

# Ask infrastructure questions
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?

Example Workflows

Performance Investigation:

Investigate why our application response times increased this afternoon

Resource Optimization:

Analyze memory usage patterns and suggest optimization strategies

Alert Analysis:

Explain the current active alerts and their potential impact

💡 Advanced Usage: Codex CLI can combine observability data with code generation capabilities for powerful DevOps workflows. Learn about the opportunities and security considerations in AI DevOps Copilot.

Troubleshooting

MCP Server Not Starting

• Check the command path exists and is executable
• Increase startup_timeout_sec for slow-starting servers
• Verify network connectivity to Netdata

Connection Timeouts

• Ensure Netdata is accessible: curl http://YOUR_NETDATA_IP:19999/api/v3/info
• Increase timeout values in configuration
• Check firewall rules between Codex CLI and Netdata

Limited Data Access

• Verify the Authorization header is set to Bearer <your key>
• Ensure the Netdata agent is properly configured for MCP
• Check that MCP is enabled in your Netdata build

Windows Issues

• MCP servers may have issues on Windows
• Consider using WSL (Windows Subsystem for Linux)
• Check GitHub issues for Windows-specific workarounds

Advanced Configuration

Multiple Environments

Configure different Netdata instances for different purposes:

# Production environment
[mcp_servers.netdata_prod]
command = "/usr/sbin/nd-mcp"
args = ["ws://prod-parent.company.com:19999/mcp"]
env = { "ND_MCP_BEARER_TOKEN" = "${PROD_API_KEY}" }
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.netdata_staging]
command = "/usr/sbin/nd-mcp"
args = ["ws://staging-parent.company.com:19999/mcp"]
env = { "ND_MCP_BEARER_TOKEN" = "${STAGING_API_KEY}" }

[mcp_servers.netdata_local]
command = "/usr/sbin/nd-mcp"
args = ["ws://localhost:19999/mcp"]
env = { "ND_MCP_BEARER_TOKEN" = "${LOCAL_API_KEY}" }

Timeout Configuration

Adjust timeouts based on your network and query complexity:

[mcp_servers.netdata]
command = "npx"
args = [
  "mcp-remote@latest",
  "--http",
  "http://remote-netdata:19999/mcp",
  "--allow-http",
  "--header",
  "Authorization: Bearer NETDATA_MCP_API_KEY"
]
startup_timeout_sec = 30  # Time to wait for MCP server to start
tool_timeout_sec = 180     # Time limit for individual tool calls

Documentation Links

• OpenAI Codex CLI GitHub Repository
• Codex CLI Configuration Documentation
• Codex CLI Installation Guide
• Netdata MCP Setup
• AI DevOps Best Practices