How to install Grok Build and run the coding-agent TUI

Grok Build is xAI’s extensible coding agent. Use it from a mouse-interactive fullscreen TUI, headlessly in scripts or bots, or through the Agent Client Protocol (ACP) in other apps. This guide follows the official docs: install the grok CLI, start an interactive or headless session, then point config.toml at a custom model or MCP server.

Install the grok CLI

On macOS, Linux, or WSL:

curl -fsSL https://x.ai/cli/install.sh | bash

On Windows (PowerShell):

irm https://x.ai/cli/install.ps1 | iex

Start an interactive session

From a repo:

cd your-project
grok

On first launch, Grok opens a browser for authentication. In non-browser environments, use an API key:

export XAI_API_KEY="xai-..."
grok

Useful first prompts:

Explain this repo.
@src/main.rs Walk me through this file.

Many settings are available in the TUI under /settings. Switch models inside the TUI with /model <name>.

Run headlessly

Headless usage is ideal for scripts, automations, or integration into other apps:

grok -p "Explain this codebase"
grok -p "Explain the architecture" --output-format streaming-json

Custom models in config.toml

Grok supports any custom model. Add it to your user-level config file, ~/.grok/config.toml (on Windows, %USERPROFILE%\.grok\config.toml):

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

To configure the default home directory, set $GROK_HOME. Settings are persisted under ~/.grok/config.toml (or $GROK_HOME/config.toml).

After updating the file, inspect what Grok discovered in the current directory — including config sources, instructions, skills, plugins, hooks, and MCP servers — then pick the model in headless mode or in the TUI:

grok inspect
grok -p "Hello" -m my-model

Grok merges several scopes. Use GROK_* (and related) environment variables for session and CI overrides. User defaults live in ~/.grok/config.toml or $GROK_HOME/config.toml. Project files at .grok/config.toml are limited to MCP servers, plugins, and permission rules — not a full user config. Managed defaults can live in ~/.grok/managed_config.toml and /etc/grok/managed_config.toml; policy pins in ~/.grok/requirements.toml and /etc/grok/requirements.toml.

Prefer /settings for UI, notifications, and other in-app options. The settings docs include a longer example config.toml with model entries, MCP server blocks, and UI options. Always confirm with grok inspect.

The same model that powers Grok Build, grok-4.6, is also available directly on the xAI API if you want it in your own agent loop, IDE integration, or coding tool.

Add MCP servers

MCP servers expose external tools to Grok. Once configured, their tools are available alongside the built-in ones, namespaced as <server>__<tool>.

The fastest way is the grok mcp command:

# Local stdio server; everything after -- is the server command
grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# Remote server over HTTP (OAuth handled automatically)
grok mcp add --transport http linear https://mcp.linear.app/mcp

# Remote server with a static auth header (--header is repeatable)
grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

grok mcp list shows configured servers, grok mcp remove <name> deletes one, and grok mcp doctor [name] diagnoses configuration and connectivity. list and doctor take --json for machine-readable output.

Servers can also be declared directly in ~/.grok/config.toml:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
env = { API_KEY = "${MY_API_KEY}" }   # ${VAR} expands at load time
startup_timeout_sec = 30              # default 30
tool_timeout_sec = 6000               # default 6000

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { "x-mcp-session-id" = "{{session_id}}" }

Grok expands ${VAR} (and ${VAR:-default}) in url, command, args, env, and headers, so secrets can stay in the environment. Servers that require OAuth trigger a browser flow on first use; tokens are stored under ~/.grok/mcp_credentials.json.

Pass --scope project to grok mcp add (it writes .grok/config.toml in the current directory) to define servers that ship with the repo. When loading, Grok walks from the current directory up to the git root reading each .grok/config.toml, and a project server with the same name as a user one replaces it entirely.

In the TUI, /mcps opens the MCP tab of the extensions modal: toggle a server with Space, refresh after config edits with r, authenticate OAuth servers with i, and add or remove with a and x.

Grok also loads MCP configurations from ~/.claude.json, .cursor/mcp.json, and project .mcp.json files, merged below config.toml in priority. Disable a vendor with [compat.claude] mcps = false or [compat.cursor] mcps = false. grok inspect shows every loaded server and its origin.

grok mcp doctor is the first stop for troubleshooting. For stdio servers that start but fail to connect, Grok captures stderr to ~/.grok/logs/mcp/<server>.stderr.log. Cold-start npx servers that download packages on first launch may need a higher startup_timeout_sec.

Next step

Install the CLI, cd into a repo, and run grok to open the TUI. Then run grok inspect so you can see which configs, skills, plugins, hooks, and MCP servers Grok loaded. When you need extra tools, add a server with grok mcp add and confirm it with grok mcp list and grok mcp doctor.