MCP Servers

添加 Server

最快的方式是使用 grok mcp 命令：

# 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 显示已配置 servers，grok mcp remove <name> 删除一个 server，grok mcp doctor [name] 诊断配置和连接。list 和 doctor 接受 --json 以提供机器可读输出。

Servers 也可以直接在 ~/.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 会展开 ${VAR}（以及 ${VAR:-default}），该机制适用于 url、command、args、env 和 headers，因此 secrets 可以保留在环境变量中。需要 OAuth 的 servers 首次使用时会触发浏览器流程；token 存储在 ~/.grok/mcp_credentials.json 下。

项目 Scope

传递 --scope project 给 grok mcp add（它会在当前目录写入 .grok/config.toml），以定义随 repository 分发的 servers。加载时，Grok 从当前目录向上遍历到 git 根目录，读取每个 .grok/config.toml；与用户 server 同名的项目 server 会完整替换用户 server。

在 TUI 中

/mcps 打开 extensions modal 的 MCP tab：按 Space 切换 server；配置修改后按 r 刷新；按 i 对 OAuth servers 进行身份验证；按 a 和 x 添加或移除。

兼容性

Grok 还会从 ~/.claude.json、.cursor/mcp.json 和项目 .mcp.json 文件加载 MCP 配置，并以低于 config.toml 的优先级合并。使用 [compat.claude] mcps = false 或 [compat.cursor] mcps = false 禁用某个 vendor。grok inspect 会显示每个已加载 server 及其来源。

故障排查

首先运行 grok mcp doctor。对于能够启动但无法连接的 stdio servers，Grok 会将 stderr 捕获到 ~/.grok/logs/mcp/<server>.stderr.log。首次启动时下载 package 的冷启动 npx servers 可能需要更高的 startup_timeout_sec。