grok-delegate (MCP)

⚡ Host loop (Session v1.2)

Unofficial bridge. Save host tokens:

1. grok_agent_session_begin({"goal":"…","host_budget":"small"})

2. Loop grok_agent_session_next → do only card (host_cmd | mcp_tool | end)

3. Stop when done=true

Skill grok-mcp v1.0 enforces this. No OAuth in MCP config — CLI login only.

Claude / Cursor orchestrate → Grok CLI codes (worktrees, receipts, token economy).

Unofficial community project — not xAI, Grok, Anthropic, or OpenAI.
Auth = local grok login only. Never put OAuth/API keys in MCP config.

Related MCP server: Grok Plugin Codex

Install (one command)

curl -fsSL https://raw.githubusercontent.com/zai-one/grok-mcp/main/scripts/install.sh \
  | bash -s -- --project "$HOME/code/my-project"

Windows: irm https://raw.githubusercontent.com/zai-one/grok-mcp/main/scripts/install.ps1 | iex

Then:

grok login
~/.local/share/grok-mcp/.venv/bin/python -m grok_delegate --self-test

Merge ~/.config/grok-mcp/mcp/claude_desktop.snippet.json into Claude/Cursor → restart → grok_agent_status.

Claude Code, on this repository

A project-scoped .mcp.json ships in the repo, so opening it in Claude Code wires grok-delegate with no install step — the package has no runtime dependencies. The entry resolves the package from CLAUDE_PROJECT_DIR, which Claude Code sets in the server's environment, so it does not depend on the working directory the host happens to use.

The command defaults to the Windows py launcher. Elsewhere, point it at your interpreter:

export GROK_MCP_PYTHON=python3

This path skips the installer, so nothing writes the env file for you. Read-only tools such as grok_agent_status work immediately; anything that touches a repository fails closed until you grant an exact root, because the allowlist is empty by design:

export GROK_DELEGATE_ALLOWED_ROOTS=/path/to/project   # ';' separates several
export GROK_DELEGATE_LANES_PARENT=/path/to/.grok-mcp-lanes

Set them where the host will inherit them, then restart it. grok_agent_status reports what was actually granted under roots.allowed. A child of an allowlisted root is not implicitly trusted.

Letting the host grant the current project

Maintaining that list by hand gets old once you work across several projects. The host already knows which directory you opened — Claude Code exports it to the server as CLAUDE_PROJECT_DIR — so the server can take the allowlist from there:

export GROK_DELEGATE_TRUST_HOST_ROOTS=1

With it set, the directory the session was launched in joins the allowlist and no longer needs to be listed. It widens the list rather than replacing it: anything in GROK_DELEGATE_ALLOWED_ROOTS stays granted, and exact-equality membership is unchanged — a sibling or a child of the session directory is still refused.

Off by default, and deliberately. Granting a root because the host named it means the operator's explicit list is no longer the whole answer; that is a fair trade when the host is your own editor, but it is yours to make. grok_agent_status shows roots.host_root_trusted and roots.host_root so a root you never typed is traceable.

Hosts that do not set CLAUDE_PROJECT_DIR are unaffected — the flag then grants nothing. Reading the host's roots over MCP roots/list, which would also cover --add-dir directories and non-Claude hosts, needs a bidirectional stdio loop this server does not have yet.

Skill (router): grok-mcp — see docs/SKILLS.md

Full easy guide: docs/EASY.md

What it is

Optional

• VPS · FastMCP · Economy

• Skills · Security · Examples

# day-to-day
grok-mcp          # launcher from installer
# or
python -m grok_delegate.server