A
licenseNot graded
qualityC
maintenanceEnables sandboxed file operations via MCP tools, resources, and prompts, with a Claude CLI client and Groq-powered web UI for file CRUD, search, code review, and documentation generation.
MIT
grok-build-mcp-server
by Nuruvala
Run headless Grok Build agents from any MCP client, with permission controls, progress streaming, background execution, and session management.
Run Grok agents (
grok): send prompts, choose models/effort/max turns, resume/continue/fork sessions, allow/deny tools, and set read-only, write, or full permission levels.Review git diffs (
review): review uncommitted changes, a merge-base diff against a ref, or a single commit; optionally return structured findings; always read-only.Research the web (
websearch): ask questions, tune result count/depth, and get metadata on which searches/sources were actually used.Manage background runs (
status,stop): launch long jobs detached, poll or wait on them, and terminate them; finished runs replay full results.Inspect sessions (
sessions): list, search, and look up local Grok sessions with resume commands.Check readiness (
check) and CLI help (help): verify binary, version, auth, permission ceiling, and defaults.
Provides tools for reviewing Git diffs and repositories, including working tree changes, merge-base diffs against a ref, and individual commits.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grok-build-mcp-serverreview the current git diff and suggest improvements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
grok-build-mcp-server
An MCP stdio server that exposes the Grok Build
CLI (grok) as tools you can call from Claude Code, Cursor, VS Code, or any other MCP client.
Claude Code ──stdio/MCP──▶ grok-build-mcp-server ──spawn──▶ grok CLI ──▶ xAI APIIt is a thin process wrapper. It does not reimplement agent logic and does not talk to the xAI API
directly — all the intelligence stays in the grok CLI. What this server adds is faithful argument
construction, robust process supervision, and clean MCP-shaped output.
Status: 0.2.2. The tool surface is complete. The server runs real headless Grok agents in the foreground or detached in the background, streams progress while they run, stops a run on request, reviews git diffs, researches questions on the web, lists the sessions those runs created, and reports session, usage, and cost. See CHANGELOG.md for what shipped and ROADMAP.md for what was considered and rejected.
Progress
A long agent run is visible while it happens, rather than a silent wait ending in a wall of text.
When your client sends a progressToken, the server runs Grok with --output-format streaming-json
and forwards a notification per event:
#5 list_dir .
#6 read_file README.md
#7 read_file — completed
#8 thinking: the user asked me to list files, read README.md, then …
#10 writing: DONE
#11 finished: end_turn (2 turns)Progress tracks what the agent is doing, not what phase it is in. Reasoning and response text are
coalesced so a token stream does not flood your client, while tool calls are reported as they
happen. Clients that support resetTimeoutOnProgress will not time out mid-run.
A client that sends no progressToken gets the cheaper non-streaming path and pays nothing for
this.
Related MCP server: Claude Code MCP Bridge
Requirements
Grok Build CLI 1.0.0 or newer, authenticated (
grok modelsshould succeed)Node.js 22 or newer
If grok is not on your PATH, set GROK_BINARY to its full path when you register the server.
Install
Claude Code
claude mcp add grok-build -s user -- npx -y grok-build-mcp-server-s user registers the server for your whole account rather than for the directory you happen to be
in. Without it the scope is that one project, which is rarely what you want for a general coding
assistant, and the symptom is a server that is missing the next time you start Claude Code somewhere
else.
Then, in Claude Code:
> use the grok-build check toolcheck reports the resolved binary, the CLI version, whether you are authenticated, and the active
permission ceiling. If it is happy, the rest will work.
Any other MCP client
The server speaks MCP over stdio and takes no arguments of its own:
{
"mcpServers": {
"grok-build": {
"command": "npx",
"args": ["-y", "grok-build-mcp-server"]
}
}
}VS Code and Cursor accept the install badges at the top of this page, which carry exactly that configuration.
Clients that install from the MCP Registry know this
server as io.github.Nuruvala/grok-build-mcp-server. The registry entry is published from the same
tag as the npm release and points at the same package.
If npx cannot find the server
npx resolves a bare package name against the local project first. If your MCP client's working
directory is a checkout of this repository — or of anything else whose package.json is named
grok-build-mcp-server — npx -y grok-build-mcp-server runs the local entry point, does not find
one, and fails with command not found. Install it somewhere of its own and register that path:
npm install --prefix ~/.local/share/grok-build-mcp grok-build-mcp-server
claude mcp add grok-build -s user -- ~/.local/share/grok-build-mcp/node_modules/.bin/grok-build-mcp-serverPermissions
Grok runs launched through this server are read-only by default: --permission-mode plan with
--sandbox read-only. Nothing can modify your files until you say so.
Permission is a ceiling, set once when you register the server, rather than a prompt on every call. Three levels:
Level |
|
| What it allows |
|
|
| Reading and reasoning. No edits |
|
|
| Edits inside the working directory |
|
|
| Unattended full approval |
The sandbox is not advisory, and a refusal is not a warning. Under write the run cannot write
outside cwd, and a refused tool call ends the whole run: the CLI reports
stopReason: cancelled, exits 0, and returns only whatever the model had said before the refusal.
The server names the refused call and its path in that case, so a refused tool is not mistaken for a
model that gave up. The server can see which call failed, not why the CLI refused it. If a run must
write somewhere else, say a report outside the repository, either point it at a path inside cwd or
use full.
write uses --permission-mode auto rather than acceptEdits, which is measured rather than
inherited from the flag's name. Headless grok has no human to accept an edit, so under
acceptEdits, dontAsk and default every file mutation is refused and the run dies, on both
sandbox profiles. auto and bypassPermissions both work; auto is the narrower one, and it still
refuses a write outside the workspace, so full remains a real step up rather than a synonym.
To let Grok make edits:
claude mcp add grok-build -s user \
-e GROK_MCP_PERMISSION_CEILING=write \
-e GROK_MCP_DEFAULT_PERMISSION=write \
-- npx -y grok-build-mcp-serverUse full only if you already run your MCP client with full approval and want the delegated Grok
run to be equally unattended. It grants the spawned grok process the same authority you have.
A call that requests more than the ceiling is rejected, not silently downgraded — a clamped run would report success while changing nothing, which is worse than a clear error.
Environment variables
Variable | Default | Purpose |
|
| Path to the |
|
| Highest level any call may request |
|
| Level used when a call requests none |
|
| Model when a call omits one. |
|
| Reasoning effort when a call omits one. |
|
| Wall clock for a single run |
|
| Background job records |
|
| Background runs alive at once. |
|
|
|
| off | Also emit |
Grok's own variables (XAI_API_KEY, GROK_HOME, GROK_DISABLE_AUTOUPDATER) pass through to the
child process untouched.
Tools
Tool | Read-only | Purpose |
| by ceiling | Run a headless Grok agent. Prompt, session resume/continue/fork, model, effort, tool allow/deny |
| always | Review a git diff: working tree, a merge-base diff against a ref, or a single commit |
| always | Research a question on the web, and report which searches and sources it actually used |
| always | Poll a background run, or list recent ones |
| no | Terminate a background run's process tree |
| always | List, search, and look up the Grok sessions on this machine |
| yes | Server version, resolved binary, |
| yes |
|
review
The diff is collected in-process and embedded in the prompt, so the model does not spend turns rediscovering what it is meant to review.
> review my working tree with grok-build
> review the diff against origin/mainTargets are uncommitted, base: "<ref>" (a merge-base diff, so commits that landed on the base
after you branched are not attributed to you), or commit: "<sha>". With none given it
auto-detects: the upstream diff when your branch is ahead, otherwise the working tree — and it says
which it chose rather than guessing silently.
review is always read-only, whatever GROK_MCP_PERMISSION_CEILING allows. It takes no
permission, write, or yolo argument, because a review that edits the code under review is
never what was wanted.
Pass structured: true for machine-readable findings (severity, file, line, summary,
rationale) on _meta.findings, validated before you see them.
Two different things can go wrong, and they are reported differently rather than blurred together:
The run never finished — it was cut off, or ended without producing its findings. There is no review, so the call is
isError: trueand_meta.findingsCompleteisfalse. The body leads with why, quoting the CLI's own reason, and names the fix that fits the actual cause.The run finished but its output will not validate. The call still succeeds, returning the raw text plus a
_meta.parseError— a degraded review beats a failed one.
What you will never get is a plausible-looking finding that the model made up. --json-schema
constrains every message the model emits, so while it is still reading it has no way to say "I am
working" except in the shape of a finding — and left unchecked it does exactly that. The schema
carries a required status field to keep that narration out of your results, and nothing is ever
salvaged from a partial response by pattern-matching.
Structured reviews of large targets do fail this way with some regularity. The failure is loud by design.
A review that reaches for a shell is refused, not killed. In headless mode an unapprovable tool
request cancels the entire run while the CLI still exits 0, so review denies the shell and edit
tools outright — the model is told no and finishes its review instead of dying mid-sentence.
websearch
> websearch: what changed in the latest Bun release?
> search the web for how Postgres handles advisory lock contention, in depthnumResults (1–50) and searchDepth (basic or full) shape the prompt — the grok CLI has no
flags for either, and neither parameter pretends otherwise. They do work: the same question asked at
basic made one search across two pages, and at full made six searches across three, for two and
a half times the cost.
The result tells you what was actually looked up, not just what the model wrote:
[1 web search, 9 sources]with _meta carrying webSearches, webToolCalls, searchQueries, sources, sourceCount,
pagesOpened, and searchPerformed. That matters more than it sounds. Grok can research through
web search or through X, and when the web is unavailable it will quietly do the second — answering
confidently, citing x.com, exiting successfully. The prose gives you no way to tell. So a run that
searched X and not the web says so in its first line and reports xSearches separately, and a run
where nothing came back at all is an error rather than a confident-looking answer from the model's
own memory:
No search ran. The answer below is the model's own prior knowledge, not current sources.searchPerformed means sources came back — not that a search was attempted. A search that started
and never returned, or returned an empty result set, is reported as what it was.
Like review, websearch is always read-only and takes no permission, write, or yolo
argument. It never passes --disable-web-search.
Background runs, status, and stop
A long agent run does not have to occupy your client. Pass background: true to grok, review,
or websearch and the call returns a runId immediately, while a detached worker process runs the
job to completion:
> have grok refactor the parser in the background
> status
> status the run from a minute ago and wait 30s for it
> stop that runThe run belongs to the machine, not to this server: it keeps going if your MCP client disconnects,
if the server restarts, or if you close your editor. Records live under GROK_MCP_STATE_DIR, one
directory per run.
status on a finished run returns what the synchronous call would have returned — same text,
same metadata, same error flag. Background is a transport for a tool call, not a second
implementation of one. While a run is live you get its state, elapsed time, both process ids, and
the tail of its progress log; waitMs blocks for up to two minutes and forwards progress
notifications as they arrive. A timed-out wait is not an error.
Two kinds of dishonesty are ruled out by construction. A run whose worker process no longer exists
is reported as abandoned rather than as still running — the machine rebooted, or something killed
it. And a run that finished early is labelled as such:
mfk2p1x9-3ac71f0b completed (cut off: cancelled) grok 4m 12s refactor the parserValidation still happens before you get a runId: a request above GROK_MCP_PERMISSION_CEILING, or
a contradictory pair of session flags, is rejected as a failed call rather than accepted and then
failed in a process nobody is watching.
stop ends a run early. It signals the worker's whole process group — the worker and the grok
process it spawned — with SIGTERM, then SIGKILL if that is not enough. Stopping an already-finished
run is not an error, and neither is stopping one that finished a moment before your call landed.
A stop that could not kill the process tree is reported as a failure, not as a stopped run. If
there is nothing to signal, or the kill is refused, or the tree survives SIGKILL, the run is left
reading running and the call returns an error naming the pid. A cancelled record sitting next to
a live process would be the tidier answer and the useless one.
A run you stop mid-flight has usually already produced something worth keeping, and both the partial result and the session id are preserved:
Stopped run msxji60o-8f5e27c4 (grok, ran 20s).
Signalled SIGTERM to process group 1703005; the tree exited.
The run was cancelled mid-flight, but it recorded a session before it ended:
grok -r 01a010e2-478c-73d2-bce9-23552245c64dGrok only reports a session id when a run reaches its end, which a stopped one never does — so that
id is read back from the CLI's own session store rather than reconstructed. _meta.sessionIdSource
tells you which you have. If two runs in the same directory could both match, you get the candidate
ids and no resume command: resuming the wrong session continues somebody else's work.
sessions
Every Grok run leaves a session on disk, and every session id this server reports can be resumed later — from any directory, by you in a terminal or by another tool call.
> list my recent grok sessions
> what grok sessions did I run in this repo?
> find the grok session about the rate limiterSessions are read from $GROK_HOME/sessions (default ~/.grok/sessions), which is the CLI's own
store, so they survive restarts of this server, of your MCP client, and of your machine. Pass id
for one session, query for a case-insensitive search over titles, first prompts, and ids, cwd to
scope to one project, and limit to bound the list.
A run that has just finished has no title yet — Grok fills those in later, if at all — so rows fall
back to the first prompt of the session, and titleSource tells you which you are looking at. Every
row carries resumeCommand, and so does every grok and review result:
grok -r 01a00c8d-970c-7531-8a12-31dac582c22bSearch is local-only. grok sessions search also consults a remote index; this tool does not, so a
session that exists only server-side will not appear.
Development
npm install
npm run build # tsc -> dist/
npm run dev # tsx src/index.ts
npm test # node --test via tsx
npm run test:coverage # same, with enforced coverage floors
npm run lint
npm run typecheck
npm run formatdocs/api-reference.md — every tool's parameters, result text,
_metakeys, and the exact conditions under which each is set.docs/security.md — what registering this server authorises, what each permission level actually grants, and what leaves your machine.
docs/engineering.md — how code is written here: architecture, functional TypeScript rules, error and effect discipline, testing and coverage policy, commit workflow.
CLAUDE.md — project background and the verified
grokCLI behaviour this server depends on.ROADMAP.md — milestones, acceptance criteria, and the ideas that were measured and rejected.
Releasing
Bump version in package.json, move the Unreleased section of CHANGELOG.md
under the new version heading, commit, then:
git tag -a v0.2.0 -m v0.2.0 && git push origin v0.2.0.github/workflows/release.yml runs the full gate, refuses to
publish if the tag and package.json disagree, installs the packed tarball into a scratch directory
and drives a real initialize against the installed binary, then publishes that same file and
cuts a GitHub release.
There is no publish credential to manage. Authentication is
npm trusted publishing: the workflow exchanges a
short-lived OIDC token, and npm generates the provenance attestation on its own. The trust is
registered against this repository and this workflow's filename, so renaming release.yml
breaks publishing — and npm does not check the configuration until a publish is attempted, where the
symptom is ENEEDAUTH rather than anything that names the cause.
License
MIT — see LICENSE.
Available Tools
8 toolscheckCheck Grok Build readinessARead-onlyIdempotent
Report grok-build-mcp-server status: version, resolved grok binary, permission ceiling, CLI readiness (grok version, grok models), and run defaults. Call this first when a grok tool behaves unexpectedly.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by detailing exactly what is reported (version, binary, permission ceiling, CLI readiness, run defaults), giving the agent concrete expectations about the output. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveys all necessary information without filler. It is front-loaded with the purpose and lists specific outputs. Slightly dense but efficient; no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully captures what the tool does and what it returns. It is self-contained: an agent reading it knows exactly when to call it and what information to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 params), and schema coverage is trivially 100%. Per calibration, baseline is 4. The description has no need to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and resource ('grok-build-mcp-server status'), clearly stating it outputs version, binary, permission ceiling, CLI readiness, and run defaults. It distinguishes from siblings by noting it is the first diagnostic step when a grok tool misbehaves, separating it from tools like 'grok', 'status', and 'help'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call this first when a grok tool behaves unexpectedly,' providing a clear when-to-use directive. It does not mention exclusions or alternatives, but the context is sufficient for an agent to decide to invoke it for troubleshooting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grokRun Grok BuildA
Run a headless Grok Build agent (grok -p). Returns the model text plus session, usage, and cost metadata. Permission is capped by GROK_MCP_PERMISSION_CEILING; requests above it are rejected rather than silently downgraded.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Absolute path. Working directory for the run. Passed as `--cwd`. Use the narrowest useful path. Under `permission: "write"` this is also the sandbox root: the run cannot write outside it, and a refused write ends the whole run. Name an output path inside `cwd`, or use `full`. | |
| deny | No | Repeatable deny rules in `ToolPrefix(glob)` form, e.g. `Read(.env)`. | |
| yolo | No | Shorthand for `permission: "full"`. Ignored when `permission` is set. `false` is not a request. | |
| agent | No | Named subagent to run, passed as `--agent`. | |
| allow | No | Repeatable allow rules in `ToolPrefix(glob)` form, e.g. `Bash(npm*)`, `Write(src/**)`. | |
| model | No | Model id to pass as `--model`. Omit to use the server default. Unknown ids are rejected by the CLI, not by this server. | |
| rules | No | Extra system-prompt text, passed as `--rules`. Longer system-prompt text belongs in the prompt. | |
| tools | No | Internal tool ids to allow, passed as a single comma-joined `--tools`. Shell is `run_terminal_command`, not `bash`. | |
| write | No | Shorthand for `permission: "write"`. Ignored when `permission` is set. `false` is not a request. | |
| effort | No | Reasoning effort passed as `--effort`. Omit to use the server default. Values are passed through; the CLI rejects what the model does not advertise. | |
| prompt | Yes | The task for Grok to perform. Passed verbatim as `grok -p`. | |
| resume | No | Resume an existing session by id or title (`--resume`). Mutually exclusive with `continueSession`. Combine with `forkSession` to fork rather than continue in place. | |
| maxTurns | No | Maximum agentic turns. Passed as `--max-turns`. Headless only. | |
| sessionId | No | Create a NEW session with this UUID (`--session-id`). Cannot be combined with `resume` or `continueSession`; use `forkSession` to name a fork. | |
| background | No | Run detached and return a runId immediately instead of waiting. Poll with the `status` tool. The run survives a restart of this MCP server. `false` is not a request. | |
| permission | No | Permission level for this run: `read-only` (plan mode, read-only sandbox), `write` (accepts edits, sandboxed to `cwd`), or `full` (no sandbox). Must be at or below GROK_MCP_PERMISSION_CEILING. Omit to use the server default. A tool call the sandbox refuses ends the run with `stopReason: cancelled`, so pick the level from where the run must write, not only from what it must change. | |
| forkSession | No | UUID for a forked session. Requires `resume` or `continueSession`. Passed as `--fork-session --session-id`. | |
| continueSession | No | Continue the most recent session for `cwd` (`--continue`). Mutually exclusive with `resume`. `false` is not a request. | |
| disallowedTools | No | Internal tool ids to block, passed as `--disallowed-tools`. | |
| disableWebSearch | No | Pass `--disable-web-search`. `false` is not a request. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds useful behavioral details: the run is headless, it returns model text plus session/usage/cost metadata, and requests above GROK_MCP_PERMISSION_CEILING are rejected rather than silently downgraded. It does not over-explain advanced semantics already covered in the schema, and there is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every clause earns its place: it states the command, indicates the return payload, and calls out the critical permission-boundary behavior. No fluff or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a large 20-parameter tool with no output schema, the description gives essential orientation: what it does, what it returns, and the permission cap. The backing schema supplies the rest. It stops just short of a 5 because it does not summarize the long-running or side-effecting nature of an agent run beyond what annotations and schema already convey.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 20 parameters with detailed, self-contained descriptions, so the tool description does not need to elaborate. The description adds no parameter-specific detail beyond the permission ceiling note, but the schema carries the burden and does so well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Run a headless Grok Build agent (`grok -p`)". It clearly distinguishes this from sibling utility tools like status, check, review, and stop by identifying it as the execution/run tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the tool to invoke a headless Grok Build run, and it adds a meaningful note about permission ceilings. It does not explicitly name alternatives or say when not to use it, but its role as the main run tool is strongly implied and differentiated from sibling inspection/control tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
helpGrok CLI helpARead-onlyIdempotent
Show the grok CLI help text. Runs grok --help and returns its stdout.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds value by revealing the implementation detail that it runs `grok --help` and captures stdout, which is behavioral context beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states the purpose, the second provides implementation details. Both are essential for the agent to understand the tool's behavior. Excellent front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters, no output schema, and very simple behavior. The description fully captures what the tool does, how it works (runs a command), and what it returns (stdout). For a help tool, this is completely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (no parameters exist). The description mentions no arguments, which is consistent. With 0 parameters, the baseline is 4, and the description adds no further info about parameters because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs `grok --help` and returns its stdout, specifying the exact verb ('show'), resource ('Grok CLI help text'), and execution method. This distinguishes it entirely from sibling tools like `check` or `websearch`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use this tool (to show the grok CLI help text), but does not provide explicit guidance on when not to use it or mention alternatives among siblings. For a tool with 0 parameters and a narrow, well-defined purpose, this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reviewReview a git diffARead-only
Review a git diff with Grok Build. Targets the working tree (uncommitted), a merge-base diff against base, or a single commit. When none is specified, auto-detects: the upstream diff if the branch is ahead, otherwise the working tree. Always runs read-only (--permission-mode plan --sandbox read-only) regardless of GROK_MCP_PERMISSION_CEILING — this tool has no permission, write, or yolo argument, because a review that edits the code it is reviewing is never wanted. Set structured: true for machine-readable findings.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Absolute path. Repository to review. Defaults to the current working directory. | |
| base | No | Review the merge-base diff against this ref. Mutually exclusive with commit and uncommitted. | |
| model | No | Model id to pass as `--model`. Omit to use the server default. Unknown ids are rejected by the CLI, not by this server. | |
| commit | No | Review this commit. Mutually exclusive with base and uncommitted. | |
| effort | No | Reasoning effort passed as `--effort`. Omit to use the server default. Values are passed through; the CLI rejects what the model does not advertise. | |
| maxTurns | No | Maximum agentic turns. Passed as `--max-turns`. Headless only. | |
| background | No | Run detached and return a runId immediately instead of waiting. Poll with the `status` tool. The run survives a restart of this MCP server. `false` is not a request. | |
| structured | No | Return machine-readable findings via `--json-schema`. A run that stops before a final findings object fails the call with reviewIncomplete. Malformed model JSON after a normal stop degrades to raw text plus a parseError field rather than failing the call. `false` is not a request. | |
| uncommitted | No | Review the working tree (staged, unstaged, and untracked). Mutually exclusive with base and commit. `false` is not a request. | |
| instructions | No | Extra reviewer guidance, appended verbatim to the prompt. |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, so the description reinforces this by explaining why there's no write capability ("a review that edits the code it is reviewing is never wanted") and how it ignores permission ceilings. This adds valuable context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences), efficient, and front-loaded with the core purpose. Every sentence contributes unique value: targets, auto-detection, read-only guarantee, and structured mode option.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, 100% schema coverage, no output schema, and annotations present, the description covers key behavioral aspects (read-only, auto-detection, mutual exclusivity) and provides usage patterns. It doesn't explain return values, but since there's no output schema, the tool likely streams output. A slight gap is not detailing the polling flow for background runs, but overall comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter relationships (mutual exclusivity), auto-detection logic, and the purpose of structured mode, which goes beyond individual parameter schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reviews a git diff using Grok Build. It specifies the three targets (uncommitted, base, commit) and auto-detection behavior, distinguishing it from sibling tools like check, grok, or sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each target mode (working tree, merge-base diff, single commit) and the auto-detection fallback. It also clearly states that review is read-only and lacks permission/write arguments, which helps the agent avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sessionsList Grok sessionsARead-onlyIdempotent
List and search Grok Build sessions from the local store ($GROK_HOME/sessions). Search is local-only: it does not consult grok sessions search or any remote index. Pass id for a single session, query for a case-insensitive substring over title, first prompt, and id, and cwd to keep only sessions that started in that directory. A reported id resumes from any directory with grok -r <id> or the grok tool's resume argument.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Exact session id lookup. Ignores query, cwd, and limit. Falls back to a case-insensitive match. | |
| cwd | No | Keep only sessions that *started* in this directory. Resume still works from anywhere (`grok -r <id>`). | |
| limit | No | Maximum rows to return. Default 20. Ignored when `id` is set. | |
| query | No | Case-insensitive substring over title, first prompt, and id. Search is local-only: it does not consult `grok sessions search` or any remote index. |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: the local-only nature, case-insensitive substring matching, parameter interactions (id ignores others, limit ignored when id set), and the ability to resume sessions from any directory using the returned id. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at about 4 sentences, front-loading the main purpose. It includes some repetition of the local-only constraint (appears in both the main description and the query parameter description), but overall it is well-structured and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and good annotations, the description is largely complete. It explains the local store, parameter behavior, and usage of returned ids. It does not describe the output format, but this is mildly acceptable given the lack of output schema. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds substantial meaning beyond the schema: it explains the role of each parameter in a usage context, specifies that id ignores other parameters, and clarifies that limit is ignored when id is set. This provides a semantic understanding that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List and search), resource (Grok Build sessions), and scope (local store at $GROK_HOME/sessions). It explicitly distinguishes from remote search by noting it does not consult any remote index, which helps differentiate it from sibling tools like 'grok sessions search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each parameter (id for single session, query for substring search, cwd for directory filtering, limit for max rows). It also states that search is local-only and not for remote queries. However, no explicit contrast with sibling tools like 'check' or 'review' is given, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
statusPoll a background runARead-onlyIdempotent
Poll a background grok, review, or websearch run, or list recent ones. A finished run replays the original tool result — same text, same metadata, same error flag — so background is a transport, not a second implementation. A run whose worker process has vanished is reported as abandoned rather than as still running. Pass runId to inspect one run, waitMs to block until it finishes, and omit runId to list recent runs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | Bytes of progress.log to include for a live run. Default 8192. | |
| limit | No | Maximum rows to return in list mode. Default 20. Ignored when `runId` is set. | |
| runId | No | Id of a background run to inspect. Omit to list recent runs. | |
| waitMs | No | Block up to this many milliseconds for the run to finish. Default 0. Ignored in list mode. A timed-out wait is not an error. |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral details: finished runs replay the original result verbatim, abandoned runs are reported as such, and a timed-out wait is not an error. This fully informs the agent of runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first sentence states purpose, second explains result semantics, third gives parameter usage patterns. No redundancy, front-loaded with the primary action. Extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 optional parameters, no output schema, and good annotations, the description covers all necessary aspects: three operational modes, parameter interactions, special cases (abandoned, timed-out wait), and the exact replay behavior. An agent has everything needed to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already documented. The description enhances this by explaining how parameters interact (omitting runId triggers list mode, waitMs is ignored in list mode) and provides defaults (8192 bytes for tail, 20 limit). This integration-level meaning adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Poll') and resource ('background run') and explicitly lists the types of runs (grok, review, websearch). It distinguishes the tool from siblings like 'check', 'stop', and the run-initiating tools by making the polling/list usage obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each parameter combination (runId for inspection, waitMs for blocking, omit runId for listing). While it gives clear context and distinguishes the three modes, it does not explicitly state when not to use this tool or name alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stopStop a background runADestructiveIdempotent
Terminate a background grok, review, or websearch run: the worker and the grok process it spawned. Stopping an already-finished run is not an error. A run cancelled mid-flight may still have produced a resumable session id, which the result reports.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | The runId returned by a background `grok`, `review`, or `websearch` call. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotent and destructive hints. The description adds critical behavioral context beyond annotations: that it terminates both the worker and the spawned grok process, that stopping a finished run is harmless, and that a cancelled run may still yield a session id. This latter point is a non-obvious side effect that an agent must know, which is valuable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences: the first states what the tool does and its coverage, the second clarifies edge cases. No filler or redundant information. Every sentence adds distinct value, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (single parameter, no output schema, no output objects), the description fully covers the tool's purpose, parameter, side effects, and edge cases. The schema and annotations are leveraged well, leaving no obvious gaps for an agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents the one parameter (runId) with a format constraint and description. Since schema description coverage is 100%, the baseline is 3. The description adds value by explicitly linking the parameter to the return values of background calls for grok/review/websearch, reinforcing its provenance and acceptable values, which warrants an above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Terminate') and clearly identifies the resources it acts on: a background run, the worker, and the spawned grok process. It also distinguishes from siblings by naming the three run types it applies to (grok, review, websearch), making its scope precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance by listing the types of runs it applies to (grok, review, websearch). It also explains a borderline case ('stopping an already-finished run is not an error'), which helps the agent decide when to use this tool without hesitation. However, it does not explicitly state when not to use it or name alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
websearchSearch the web with Grok BuildARead-only
Research a question with Grok Build's web search. numResults and searchDepth shape the prompt only — the CLI has no flags for either. Always runs read-only (--permission-mode plan --sandbox read-only) regardless of GROK_MCP_PERMISSION_CEILING — this tool has no permission, write, or yolo argument, because a search never needs to write. Never passes --disable-web-search.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Absolute path. Working directory for the run. Passed as `--cwd`. Defaults to the current working directory. | |
| model | No | Model id to pass as `--model`. Omit to use the server default. Unknown ids are rejected by the CLI, not by this server. | |
| query | Yes | The question to research. Passed as the body of a web-search-shaped prompt. | |
| effort | No | Reasoning effort passed as `--effort`. Omit to use the server default. Values are passed through; the CLI rejects what the model does not advertise. | |
| maxTurns | No | Maximum agentic turns. Passed as `--max-turns`. Headless only. No default — a cap is how a run gets cut off mid-research. | |
| background | No | Run detached and return a runId immediately instead of waiting. Poll with the `status` tool. The run survives a restart of this MCP server. `false` is not a request. | |
| numResults | No | Prompt-level target for how many distinct sources to cite, not a backend limit. The CLI has no `--num-results` flag. | |
| searchDepth | No | Prompt-level search depth. `basic` (default) asks for one round; `full` asks for more than one, from different angles. The CLI has no `--search-depth` flag. | |
| instructions | No | Extra researcher guidance, appended verbatim to the prompt. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing runtime behavior: it always runs with `--permission-mode plan --sandbox read-only` regardless of GROK_MCP_PERMISSION_CEILING, lacks permission/write/yolo arguments, and never passes `--disable-web-search`. This adds significant context not covered by the readOnlyHint and openWorldHint annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, zero filler. Each sentence adds unique information: research purpose, prompt-only parameters, fixed read-only behavior, and special flag avoidance. Front-loaded with the primary verb. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (with 100% schema coverage), rich annotations (readOnlyHint, openWorldHint), and no output schema, the description is complete enough. It covers the tool's safety profile, parameter effects, and constraints without needing to detail outputs. No gaps that would confuse an agent selecting or invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. However, the description adds value by clarifying that `numResults` and `searchDepth` only shape the prompt and have no CLI flags, and that `background` runs detached. It also explains `query` is the body of a web-search-shaped prompt. Not quite a 5 because it could weave in more hints about how `effort` and `model` interact with the CLI rejection logic, but still above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it researches a question using web search, with a specific verb ('research') and resource ('Grok Build's web search'). It distinguishes itself from siblings by explicitly noting it never needs to write, which sets it apart from write-oriented tools like grok or review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it always runs read-only with a fixed permission mode, never passes `--disable-web-search`, and explains that `numResults` and `searchDepth` only shape the prompt. It also indirectly suggests when not to use this tool (if write access or a different permission mode is needed), complementing the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
1 tool update
v0.2.4- Changed
grok2 fields changed- changed
Input schema / properties / cwd / descriptionPrevious value: -"Absolute path. Working directory for the run. Passed as `--cwd`. Use the narrowest useful path."New value: +"Absolute path. Working directory for the run. Passed as `--cwd`. Use the narrowest useful path. Under `permission: \"write\"` this is also the sandbox root: the run cannot write outside it, and a refused write ends the whole run. Name an output path inside `cwd`, or use `full`." - changed
Input schema / properties / permission / descriptionPrevious value: -"Permission level for this run: `read-only`, `write`, or `full`. Must be at or below GROK_MCP_PERMISSION_CEILING. Omit to use the server default."New value: +"Permission level for this run: `read-only` (plan mode, read-only sandbox), `write` (accepts edits, sandboxed to `cwd`), or `full` (no sandbox). Must be at or below GROK_MCP_PERMISSION_CEILING. Omit to use the server default. A tool call the sandbox refuses ends the run with `stopReason: cancelled`, so pick the level from where the run must write, not only from what it must change."
8 tool updates
v0.2.2- First observed
check - First observed
grok - First observed
help - First observed
review - First observed
sessions - First observed
status - First observed
stop - First observed
websearch
TDQS
A4.4/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: server status, agent run, code review, session management, web search, background run polling, termination, and CLI help. No two tools overlap in functionality; descriptions are explicit about roles and restrictions.
Naming Consistency3/5
Tool names are all lowercase single words without underscores or camelCase, but they lack a predictable pattern like verb_noun. Some are verbs (check, stop), some nouns (sessions, status), and 'websearch' is a compound. The naming is readable but not strictly consistent.
Tool Count5/5
With 8 tools, the server covers its core domain—running Grok Build, reviewing diffs, searching the web, managing sessions, and monitoring background tasks—without excess. Each tool feels necessary and justified for the Grok Build integration.
Completeness4/5
The tool surface covers all major workflows: running an agent, reviewing code, searching, session retrieval, and background task management. Minor gaps exist (e.g., no dedicated tool to list models or configure settings), but the core functionality is well-represented.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
- QuallaaOAuthcom.quallaa
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Give any MCP-compatible AI assistant a builder for live, hosted web tools and workflows.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceExposes Claude Code's file editing, command execution, and test running capabilities as composable MCP tools for any MCP-compatible host, enabling code operations via a stateless bridge.-
- FlicenseAqualityBmaintenanceEnables using the xAI Grok CLI as an MCP sub-agent for code review, asking questions, and continuing conversations within MCP hosts like Claude Code.4-
- AlicenseNot gradedqualityAmaintenanceEnables Codex to use Grok Build CLI as a controlled subagent via MCP tools for independent investigation, review, and isolated implementation tasks.5MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nuruvala/grok-build-to-claude'
If you have feedback or need assistance with the MCP directory API, please join our Discord server