grok-delegate (MCP)

Version 0.4.1 — Local stdio MCP bridge that delegates coding work to the host Grok CLI agent with isolated git worktrees, typed receipts, and three explicit backend transports.

Security one-liner: this repository must never contain OAuth tokens, API keys, or WebSocket secrets. Model auth is the local Grok CLI session (grok login → machine-local auth store). MCP config must only list paths and non-secret policy env vars.

Install guides

Also: SECURITY · CONTRIBUTING · ACP transports · Client setup examples

Related MCP server: Grok Plugin Codex

What it does

WebSocket note: MCP clients still connect over stdio. WebSocket is the optional ACP channel between this bridge and a local grok agent serve daemon (loopback + ephemeral secret only).

Prerequisites

• Python 3.10+

• Grok CLI installed and authenticated (grok login)

• git available on PATH

Quick install

cd <REPO_PATH>
python -m pip install -e ".[test]"

Configure allowlisted project roots (fail-closed):

export GROK_DELEGATE_ALLOWED_ROOTS="<PROJECT_ROOT>"
export GROK_DELEGATE_LANES_PARENT="<LANES_PARENT>"   # outside the repo
export GROK_DELEGATE_JOBS_DIR="<JOBS_DIR>"           # optional durable jobs

Quick run

# stdio MCP server (default entry for desktop hosts)
grok-delegate
# or:
python -m grok_delegate.server

# operator checks (no host restart needed)
python -m grok_delegate --self-test
python -m pytest -q

Connect clients

Copy a template from examples/ and replace placeholders only (<REPO_PATH>, <PROJECT_ROOT>, …). Never put GROK_AGENT_SECRET, OAuth tokens, or API keys in these files.

Full steps: docs/install/en.md.

Minimal Claude Desktop fragment

{
  "mcpServers": {
    "grok-delegate": {
      "command": "python",
      "args": ["-m", "grok_delegate.server"],
      "cwd": "<REPO_PATH>",
      "env": {
        "GROK_DELEGATE_ALLOWED_ROOTS": "<PROJECT_ROOT>",
        "GROK_DELEGATE_LANES_PARENT": "<LANES_PARENT>"
      }
    }
  }
}

First verification

1. python -m grok_delegate --self-test → PASS table

2. From the host: call grok_agent_status

3. Prefer grok_agent_consult before any execute on a real repo

4. For write roles, use a temporary git repository until receipts look correct

Transports (backend)

Details: docs/ACP-TRANSPORTS.md.

Security boundary

• No credentials in git, examples, or receipts

• Local Grok CLI session only — bridge does not read auth.json into logs

• WebSocket: loopback only, process-local secret, redacted from logs

• Deny-by-default tool permissions; no --always-approve / bypassPermissions

• Write work in external worktrees; operator merges after review

See SECURITY.md.

Development

python -m pip install -e ".[test]"
python -m pytest -q
python -m compileall -q grok_delegate tests

License

MIT — see LICENSE.