Skip to main content
Glama
segalz

xAI Grok MCP Bridge

by segalz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

x.ai Grok CLI MCP Bridge

Use the local grok CLI as an MCP sub-agent from Claude Code or any MCP host.

This server wraps the documented x.ai headless scripting mode. The generic tools use JSON output, while grok_code_review uses plain output because it produced better review results in practice.

grok --no-auto-update --prompt-file /tmp/prompt.md --cwd /path/to/project --output-format json

Requirements

  • Windows host with Python 3.10+ and WSL2

  • Grok installed and authenticated inside the selected Linux distro

  • Required GROK_WSL_DISTRO (for example Ubuntu)

  • Required GROK_CLI_PATH: absolute Linux executable path inside that distro

The bridge uses WSL only. Native Windows Grok execution and native PATH lookup have been removed. Missing WSL configuration fails before any CLI process is started.

Windows with WSL2

xAI ships grok.exe unsigned. Windows Smart App Control starts only signed, reputable binaries, so on a machine where it is enabled every invocation dies with [WinError 4551] An Application Control policy has blocked this file. The CLI is not broken; Windows refuses to launch it. Smart App Control has no per-app allowlist, and turning it off cannot be undone without reinstalling Windows, so run the Linux CLI inside WSL2 instead and keep the protection on.

Install and authenticate Grok inside the selected distro. Windows CLI login state is not used by this route.

wsl --install -d Ubuntu
wsl -d Ubuntu -- bash -lc "curl -fsSL https://x.ai/cli/install.sh | bash"
wsl -d Ubuntu -- bash -lc "~/.grok/bin/grok login"

Example MCP host configuration for this checkout:

{
  "mcpServers": {
    "xai": {
      "command": "C:\\Develop\\XAIMsp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Develop\\XAIMsp\\server.py"],
      "env": {
        "GROK_WSL_DISTRO": "Ubuntu",
        "GROK_CLI_PATH": "/home/segal/.grok/bin/grok"
      }
    }
  }
}

Adjust the checkout, distro, and Linux user paths for your installation. With GROK_WSL_DISTRO set, every call (including grok_version) uses wsl.exe -d <distro> -- <absolute Linux executable>. GROK_CLI_PATH is required and must be an absolute Linux path: WSL does not load login-shell PATH settings. Windows-side executable validation is skipped; WSL reports missing or non-executable binaries. The distro setting is required; there is no fallback to Windows grok.exe.

Pass workspace as a host path such as C:\Develop\XAIMsp. The bridge converts drive paths for --cwd and its temporary --prompt-file to /mnt/c/..., assuming standard WSL drive mounts. Custom mount roots and UNC workspaces are not supported by this conversion. Prompt files are removed on the host after the call, including failures.

Restart the MCP server after changing its configuration or code. Check grok_version first, then make a small grok_ask call to verify authentication and model access. A version check alone does not verify a model response.

Related MCP server: peer-agents-mcp

Install

cd C:\Develop\XAIMsp
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Use the MCP host configuration in Windows with WSL2. The Python MCP server runs on Windows; all Grok invocations run inside WSL.

Tools

  • grok_ask(prompt, workspace?, timeout_s?, model?, session_id?, max_turns?, reasoning_effort?, rules?, permission_mode?, raw_output?)

  • grok_continue(prompt, workspace?, timeout_s?, model?, resume?, max_turns?, reasoning_effort?, rules?, permission_mode?, raw_output?)

  • grok_code_review(code_or_diff, question?, primary_analysis?, workspace?, timeout_s?, model?, max_findings?, reasoning_effort?, self_check?, raw_output?)

  • grok_version()

workspace defaults to the MCP server's current directory. Pass the project path explicitly when you want Grok to inspect a specific repo.

Use grok_code_review as a second-opinion reviewer after the primary or manual analysis. It embeds strict offline-review rules in the prompt, disables web search, and uses --prompt-file.

Advanced parameters:

  • model: Defaults to grok-4.6 for ask, continue, and review. An explicit model overrides it.

  • permission_mode: Ask/continue accept acceptEdits, auto or readOnly. acceptEdits and auto both send --permission-mode auto, and that is also what a call sends when it passes nothing. readOnly sends no approval flag, so the CLI's own gate stands between Grok and any change, and it appends a rule telling Grok as much so it does not spend turns reaching for tools that will be refused. The gate is the boundary; the rule only saves effort. Other values are rejected. Raw output includes the requested and effective modes.

    Approval is granted by default because headless grok has nobody to ask. Without it, the first tool call needing a write or a non-read-only command ends the turn as stopReason: cancelled, returning narration instead of an answer. The grant is real: Grok can write files and run commands in the workspace without asking, and the workspace is a working directory, not a security boundary. Point it at a repository whose changes you can see and revert.

  • max_turns: Defaults to 50. Far above ordinary work, low enough that a stuck loop stops spending quota. Pass a larger value for a genuinely long task.

  • self_check=true: Passes --check for an extra Grok verification loop. Use sparingly because it costs more time and quota.

  • raw_output=true: Returns a debug payload with extracted text, stdout, stderr, return code, and parsed JSON when available.

  • session_id and resume: Useful for explicit Grok session control. session_id should be a valid UUID for new sessions.

  • rules: Available on generic ask/continue calls. Prefer grok_code_review for second-opinion code review because it already uses the tuned offline-review prompt.

Set XAI_MCP_DEBUG=true only when diagnosing bridge startup or CLI invocation issues.

See CLAUDE_CODE_USAGE.md for the recommended Claude Code workflow.

Concurrency

Calls run in parallel, up to MAX_CONCURRENT_GROK (4) at once. Grok sessions are independent processes -- xAI's own "agent swarm" runs several deliberately -- and four concurrent calls were measured here returning four correct, uncrossed answers in 10.4s against 24.8s serialised.

The bound is there because each grok is a ~166MB process and every session draws on the same account pool, so an unbounded burst costs memory and quota rather than time. Anything past the limit waits for a slot; nothing is refused.

An earlier version held a single mutex across every invocation, so a second caller always waited for the first. If you are building anything that fans work out across several calls, that is no longer the constraint it was.

Grok splits work by itself

Before building anything that fans a task out across several grok_ask calls: Grok already does this internally. Subagents are child sessions with their own context windows, enabled by default, and the main agent calls spawn_subagent when it sees work worth delegating. It survives headless invocation through this bridge -- a request naming three independent questions produced three spawn_subagent calls, 15 model calls against 3 main-agent turns, and one combined answer.

So ask for the delegation in the prompt rather than orchestrating it from outside. Splitting into separate bridge calls costs a process each and puts the recombining on the caller, which is work Grok has already done.

Security

Grok is an agentic CLI. workspace is a working directory, not a security boundary. The bridge does not expose --always-approve through MCP tools. Use grok_code_review with focused snippets or diffs, and verify findings before editing code.

Smoke Test

This makes a real Grok call and may use quota:

python test_smoke.py

Available Tools

4 tools
grok_askB

Ask Grok a prompt in a new headless CLI session.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional Grok model id passed to `--model`.grok-4.5
rulesNoOptional run-scoped rules appended to Grok's system prompt.
promptYesThe question or task for Grok.
max_turnsNoOptional limit for agent turns.
timeout_sNoMaximum seconds to wait. Default 300, capped at 600.
workspaceNoWorking directory for Grok. Defaults to this server's cwd.
raw_outputNoReturn text plus raw stdout/stderr and parsed JSON when true.
session_idNoOptional UUID for a new named headless session.
reasoning_effortNoOptional reasoning effort string passed through.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full responsibility. It only mentions a 'new headless CLI session' but omits behavioral traits like session handling, timeout behavior, authentication needs, or raw output characteristics.

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 that is concise but lacks structure. It could be expanded with a brief example or key options without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters) and presence of output schema, the description is minimally adequate. It doesn't highlight common use cases or important parameters, but combined with schema it is acceptable for a straightforward prompting tool.

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?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the input schema; it does not explain parameters like model, rules, or raw_output.

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 'Ask', the resource 'Grok', and the context 'new headless CLI session'. It effectively distinguishes from sibling tools like grok_continue (which implies continuation) and grok_code_review.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives like grok_continue or grok_code_review. The phrase 'new headless CLI session' hints at one-shot usage, but lacks clear when-to-use or when-not-to-use instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_code_reviewA

Ask Grok for a strict second-opinion code review.

This tool is intended to run after CodeHelper or manual analysis. It sends strict run-scoped review rules, disables web search, and passes large prompts via --prompt-file.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional Grok model id passed to `--model`.grok-4.5
questionNoReview focus.Find concrete correctness, security, and regression risks.
timeout_sNoMaximum seconds to wait. Default 300, capped at 600.
workspaceNoWorking directory for Grok. Defaults to this server's cwd.
raw_outputNoReturn text plus raw stdout/stderr when true.
self_checkNoPass `--check` for an extra verification loop. Costs more time/quota.
code_or_diffYesCode, diff, or focused snippets to review.
max_findingsNoMaximum findings to request. Must be 1-10.
primary_analysisNoOptional CodeHelper/manual findings to challenge.
reasoning_effortNoOptional reasoning effort string passed through.high

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses key behaviors: sends strict rules, disables web search, uses `--prompt-file` for large prompts. This adds value beyond a simple verb definition and helps the agent understand the tool's operation.

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 with no wasted words. Front-loaded with purpose and context, every sentence serves a purpose.

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 (1 required) and an output schema, the description covers core purpose, usage order, and behavioral quirks. It could mention error handling or quotas, but the schema and output schema compensate well.

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?

Schema description coverage is 100%, so baseline is 3. Description adds some context (e.g., 'passes large prompts via `--prompt-file`'), but does not significantly enhance understanding beyond the schema's detailed parameter descriptions.

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?

Description clearly states it is a strict second-opinion code review tool, distinguishing it from siblings like general Q&A (grok_ask) or continuation (grok_continue). It specifies verb 'Ask Grok for... code review' and resource 'code_or_diff'.

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 says 'intended to run after CodeHelper or manual analysis', providing clear context for when to use it. Does not explicitly state when not to use, but sibling tools imply alternatives (e.g., grok_ask for general questions).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_continueC

Continue a Grok headless session.

If resume is provided, resumes that session id. Otherwise passes --continue, which continues the most recent session in the workspace.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNogrok-4.5
rulesNo
promptYes
resumeNo
max_turnsNo
timeout_sNo
workspaceNo
raw_outputNo
reasoning_effortNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains the two continuation modes but does not disclose behavioral traits like session state mutation, rate limits, or data persistence. It lacks details on side effects of continuing a session.

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 extremely concise with two sentences. The first sentence states the purpose, and the second explains two modes. Zero wasted words, and it is well-structured for quick parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, no annotations) and presence of an output schema, the description lacks essential context. It does not define what a 'headless session' is, how to obtain a session ID, or what the output contains. It assumes prior knowledge, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only explains the 'resume' parameter and implies a '--continue' behavior, but fails to describe the other 8 parameters including the required 'prompt'. This is insufficient for a 9-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: continuing a Grok headless session. It specifies two modes (resume or --continue), providing a specific verb and resource. However, it does not explicitly distinguish from siblings like grok_ask, but the purpose is clear enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains two usage scenarios (resume a specific session or continue the most recent) but offers no guidance on when to use this tool compared to alternatives like grok_ask. There is no mention of prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_versionA

Return the installed Grok CLI version.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description fully discloses the tool's behavior: it returns the installed version. No annotations are present, but the description covers all relevant aspects (read-only, no side effects). For a tool of this simplicity, transparency is complete.

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?

A single, clear sentence that is front-loaded and avoids any unnecessary words. Every part of the description is meaningful and concise.

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 tool has an output schema (not shown but indicated) and zero parameters, the description is complete. It suffices for an agent to understand the tool's purpose and usage without ambiguity.

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?

Input schema has zero parameters with 100% coverage, so no parameter descriptions are needed. Description does not add anything beyond the schema, but baseline for 0 params is 4.

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?

Tool name 'grok_version' and description 'Return the installed Grok CLI version' clearly identify the verb (Return) and resource (Grok CLI version). It is distinct from sibling tools like grok_ask, grok_code_review, and grok_continue.

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?

While no explicit when-to-use or when-not-to-use guidance is provided, the simple nature of a version check and the sibling tools' different purposes make usage obvious. Could be improved by mentioning that it requires no arguments and is safe to call anytime.

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.

  1. 4 tool updatesv0.1.0
    • First observedgrok_ask
    • First observedgrok_code_review
    • First observedgrok_continue
    • First observedgrok_version
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: general prompting, code review, session continuation, and version checking. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent pattern: 'grok_' prefix with snake_case verb or noun suffixes (ask, code_review, continue, version).

Tool Count4/5

4 tools is on the lower end but still appropriate for a focused bridge to a CLI tool. Could be expanded slightly but not under-scoped.

Completeness4/5

Core operations are covered: prompting, code review, session continuation, and version info. Missing session management or configuration tools but minimal for the domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers