Skip to content

grok-config-valid

.grok/config.toml must parse, and its servers and permissions must load
Severity error (auto)
Autofix -
Since v0.20.0
Repo Types grok-project
Category Grok Build

Why

.grok/config.toml configures project-level settings for Grok Build, such as shared MCP servers and tool permission rules.

If the configuration contains a TOML syntax error or invalid server and permission tables, Grok Build may skip loading the file or ignore individual settings during sessions. For example, a syntax error prevents the entire file from loading, while an invalid server entry or malformed permission list can cause specific configurations to be skipped.

This rule validates the syntax and structure of .grok/config.toml to help ensure your MCP servers and permissions work reliably for all collaborators.

To verify which tables are appropriate for a project configuration file versus user configuration, see grok-config-project-scope. Server commands are also scanned for security by mcp-prohibited.

Severity

Findings distinguish between whole-file syntax errors and table-level issues:

Error — issues that prevent the TOML file from parsing:

  • Invalid TOML syntax, duplicate keys within a table, or duplicate [table] headers.

Warnings — the file parses, but specific servers or permission settings cannot be loaded:

  • mcp_servers is not a TOML table.
  • A [mcp_servers.<name>] entry that is not a table, or does not specify a command or URL string. URL fields accept url, urlTemplate, or url_template; HTTP definitions must use only one of these aliases.
  • Invalid fields in the selected transport or common server settings. Grok tries the full stdio variant before HTTP, ignoring fields outside the selected variant. A malformed stdio variant can fall through to HTTP; an enabled, blank command selects stdio and is then rejected.
  • Incorrect common types for enabled, timeouts, tool_timeouts, expose_image_base64, or nested oauth / setup values. Other servers still load when one entry is rejected.
  • Permission lists (allow, deny, ask) that are not arrays.
  • Individual entries in allow, deny, or ask that are not strings.
  • A malformed permission section, or verbose rules with invalid entries. Actions are allow, deny, or ask; tool names are lowercase Grok names. pattern must be a string and pattern_mode is glob or domain. One malformed verbose rule discards the whole list, including valid siblings.
  • Nonempty verbose rules specified alongside an array-valued allow, deny, or ask. Even an empty compact array takes precedence. A malformed compact key alone does not hide valid verbose rules; rules = [] adds no lost-rule warning. Accepted TOML enum and positional-field representations remain supported.

What is not reported

  • Unknown fields inside a server table: Grok logs these via mcpConfigProblems and loads the server normally.
  • Unknown keys inside [permission]: Grok ignores unknown keys; scope mismatches like defaultMode are covered by grok-config-project-scope.
  • The URL or command target content: whether an endpoint is live is a runtime concern.
  • Servers with enabled = false: disabled servers are valid configurations.

Examples

Bad — a syntax error in one server prevents the rest of the file from parsing:

[mcp_servers.gateway]
command = "bin/gateway"
args = ["mcp"

[permission]
allow = ["Bash(make test)"]

Bad — a server missing both command and url, and mixing allow with rules:

[mcp_servers.quayside]
args = ["mcp"]
cwd = "services/quayside"

[permission]
allow = ["Bash(make test)"]
rules = [{ action = "deny", tool = "Bash", pattern = "psql *" }]

Good — well-formed MCP servers and concise permission lists:

[mcp_servers.berths]
command = "bin/harbourmaster"
args = ["mcp", "--read-only"]

[mcp_servers.berths.env]
HARBOURMASTER_PROFILE = "readonly"

[mcp_servers.tideboard]
url = "https://tideboard.internal.example/mcp"

[permission]
allow = ["Bash(make test)"]
deny = ["Bash(psql *)"]

How to fix

  • Ensure .grok/config.toml is valid TOML syntax.
  • Provide a non-empty command or url for each server under [mcp_servers.<name>].
  • Keep args as an array of strings, and env and headers as tables of strings.
  • Choose either compact lists (allow, deny, ask) or verbose rules tables under [permission]. Using compact lists is recommended for brevity.

An explicit rule severity applies to primary file, server and field findings, including those whose normal failure scope is WARNING. With no override (or severity: null), each failure scope retains its documented default.

Configuration

rules:
  grok-config-valid:
    enabled: auto  # true | false | auto
    severity: error

Run skillsaw explain grok-config-valid to see this documentation and the rule's effective configuration in your terminal.