Add MCP servers in Grok Build

MCP (Model Context Protocol) servers expose external tools to Grok Build. Once configured, tools appear alongside built-ins, namespaced as <server>__<tool>. Official Build MCP docs cover CLI add, config.toml, project scope, TUI controls, and vendor compat files.

Add with the CLI

# 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}"

Command	What it does
grok mcp list	Show configured servers (--json for machine-readable)
grok mcp remove <name>	Delete a server
grok mcp doctor [name]	Diagnose config and connectivity (--json OK)

Declare in 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. OAuth servers open a browser on first use; tokens land in ~/.grok/mcp_credentials.json.

Project scope

grok mcp add --scope project writes .grok/config.toml in the current directory so servers ship with the repo. On load, Grok walks from cwd up to the git root reading each .grok/config.toml. A project server with the same name as a user server replaces it entirely.

TUI and compatibility

/mcps opens the MCP tab: Space toggles a server, r refreshes after edits, i authenticates OAuth, a adds, x removes.

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

Troubleshoot

grok mcp doctor is the first stop. Stdio servers that start but fail to connect write stderr to ~/.grok/logs/mcp/<name>.stderr.log. Cold-start npx servers that download packages may need a higher startup_timeout_sec.

For grok.com custom connectors (consumer surface), see Add a custom MCP connector on grok.com. Project rules: Make Grok Build follow your AGENTS.md. CLI: Install the Grok Build CLI.