Codex CLI

This guide helps you set up the mcp-grafana server for the OpenAI Codex CLI.

Prerequisites

Codex CLI installed (npm install -g @openai/codex)
Grafana 9.0+ with a service account token
mcp-grafana binary in your PATH

Important: TOML format

Codex uses TOML configuration, not JSON. Configuration file: ~/.codex/config.toml

Configuration

CLI setup (recommended)

codex mcp add grafana -- mcp-grafana

Add environment variables:

codex mcp add grafana \
  --env GRAFANA_URL=http://localhost:3000 \
  --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token> \
  -- mcp-grafana

Manual configuration

Create or edit ~/.codex/config.toml:

[mcp_servers.grafana]
command = "mcp-grafana"
args = []
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }

Note: Use mcp_servers (underscore, not hyphen).

Debug mode

[mcp_servers.grafana]
command = "mcp-grafana"
args = ["-debug"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }

Docker setup

[mcp_servers.grafana]
command = "docker"
args = ["run", "--rm", "-i", "-e", "GRAFANA_URL", "-e", "GRAFANA_SERVICE_ACCOUNT_TOKEN", "grafana/mcp-grafana", "-t", "stdio"]
env = { GRAFANA_URL = "http://host.docker.internal:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }

Verify configuration

# List configured servers
codex mcp list

# Show specific server config
codex mcp get grafana

# Start Codex and test
codex

Then ask: “List my Grafana dashboards”

Timeout settings

If Grafana operations take time, increase timeout:

[mcp_servers.grafana]
command = "mcp-grafana"
args = []
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
startup_timeout_ms = 20000
tool_timeout_ms = 120000

Troubleshooting

Server not found in Codex:

Verify TOML syntax (no trailing commas, use = not :)
Check key is mcp_servers not mcp-servers
Restart Codex after configuration changes

Config shared across CLI and IDE: Codex CLI and VS Code extension share ~/.codex/config.toml. A syntax error breaks both.

Common TOML mistakes:

# Wrong - JSON-style
env = {"GRAFANA_URL": "http://localhost:3000"}

# Correct - TOML-style
env = { GRAFANA_URL = "http://localhost:3000" }

Read-only mode

[mcp_servers.grafana]
command = "mcp-grafana"
args = ["--disable-write"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }