Click on "Deploy 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 dispatch a task to fix the failing tests and wait for it"
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.
English | 简体中文
Use the local Grok CLI as a subagent through a standard stdio MCP server. Dispatch tasks, resume conversations, inspect progress, send follow-up instructions, and interrupt work.
The server supports Codex and Claude Code. install.py registers the server and result hooks for either client at user level.
Windows, Python 3.11+, uv, and an installed, authenticated Grok CLI.
No third-party Python dependencies. uv run creates the project environment.
Grok must support ACP session configuration and closing, and the x.ai/task and x.ai/subagent extensions.
Related MCP server: Codex Control Plane MCP
git clone https://github.com/cigenb/grok-subagent-mcp.git
cd grok-subagent-mcp
uv run python install.py codex # Codex
uv run python install.py claude # Claude CodeBoth clients use the MCP server name grok and three mcp_tool hooks that call grok_collect:
PostToolUse and UserPromptSubmit collect results; Stop returns unread results or asks the model to wait for unfinished tasks.
Hooks do not wake an idle chat after its turn has ended. Uncollected results remain in the task database and can be retrieved when the conversation continues.
The installer backs up existing configuration, registers the grok MCP server in the user-level config.toml, and merges three MCP tool hooks into hooks.json.
Review and trust these definitions through /hooks in the Codex CLI, then start a new chat to load the server.
Codex uses the threadId supplied in call metadata as the source conversation.
The installer backs up ~/.claude/settings.json, registers the user-scope grok server through claude mcp add-json, and merges three hooks into settings.json. New sessions load both.
Tools appear as mcp__grok__grok_*; add mcp__grok to permissions.allow to skip per-call confirmation.
Claude Code does not send a conversation ID with tool calls. The server uses the session ID from the CLAUDE_CODE_SESSION_ID environment variable that Claude Code sets when it starts the server; this variable is not part of the documented Claude Code interface.
Resuming the same Claude session after a restart keeps access to its Grok sessions. Tasks follow the server process: if the conversation changes (for example through /clear) while the server keeps running, its earlier tasks stay with the new conversation.
Other MCP clients can use the same server with this stdio command:
uv run --directory "<install-dir>" python server.py --client claudeOther clients can supply --owner <source-conversation-id> or the source_id tool argument to preserve ownership across server restarts.
Without either, tasks are isolated to that MCP connection.
Tool | Purpose |
| Dispatch a task with required |
| Wait for this conversation's tasks; timing out or cancelling the wait does not stop execution |
| List tasks, or inspect |
| Send instructions to a running task, applied during subsequent processing |
| Interrupt a task and its subagents, preserving output and files already produced |
| Client hook interface that returns event-specific hook JSON |
The default model is regular grok-4.7 with reasoning effort high. Explicit model and effort arguments override these values; a resumed conversation inherits the last successfully applied settings when they are omitted.
These settings are independent of the interactive Grok defaults. The process disables cross-session memory, retains conversation resume, and allows Grok to use its own subagents.
Grok runs with its sandbox off and tool execution automatically approved. Every call's scope must describe allowed read/write paths, prohibited actions, and acceptance criteria.
scope is an instruction to the model, not filesystem access control. The caller must verify artifacts and tests. Grok is instructed to report files created or changed by terminal commands in its deliverable list.
A Grok conversation can have only one active main task. Resuming retains its working directory. Each task closes its native session after finishing; resuming loads the saved history. The bridge does not automatically create worktrees. Paths returned for Grok subagent worktrees are retained as artifacts. Closing the MCP connection stops its Grok process tree. After restarting the server, callers can read saved output or resume registered conversations.
Runtime data lives under ~/.grok/cigenb-grok-mcp/codex/ or claude/:
tasks.sqlite3: source conversations, main and child session IDs, status, delivery state, and artifact paths.
tasks/<task-id>/output.txt: assistant output, excluding thinking text.
tasks/<task-id>/scratch/: task temporary files.
logs/: per-process Grok diagnostics; several tasks may reference the same log.
backups/: client configuration backups made before installation.
Grok's native history remains in ~/.grok/sessions/, associated by session ID.
Shared caches, global logs, project deliverables, and worktrees are not removed with task history.
Use --client codex or --client claude to select the data partition:
uv run python manage.py --client codex list
uv run python manage.py --client codex inspect <task-id>
uv run python manage.py --client codex keep <task-id>
uv run python manage.py --client codex cleanup-plan --days 7 --out cleanup-plan.jsonDefault candidates are finished tasks whose results have been collected and whose conversation has not been used for seven days. Use --ids to select tasks explicitly.
Tasks sharing a native conversation are checked together. Active, unread, and retained tasks cannot be deleted.
The cleanup plan lists exact files, hashes, and artifacts to preserve. Review the list and obtain deletion confirmation before applying it:
uv run python manage.py --client codex cleanup cleanup-plan.json --confirm <confirmation-from-plan>Cleanup invokes grok sessions delete for registered main and child sessions; that command may also delete corresponding remote history.
If tasks or files change after the preview, cleanup refuses to proceed and requires a new plan.
Process logs become eligible only after their MCP process has exited and every referencing task is already cleaned or included in the plan.
Configuration backups are retained separately. After cleanup, the task database retains ownership, session IDs, and artifact paths, while removing task and scope text.
GROK_MCP_BIN selects the Grok executable. GROK_MCP_DATA_DIR overrides the MCP data root, primarily for isolated tests.
uv run python -m unittest discover -s tests -v
uv run python tests/smoke.pyThe second command calls Grok for real, creates files in a system temporary directory, and produces native test sessions.
Codex: run codex mcp remove grok, then remove the three handlers whose server is grok and tool is grok_collect from ~/.codex/hooks.json.
Claude Code: run claude mcp remove grok -s user, then remove the same three handlers from ~/.claude/settings.json.
Task data and native Grok history are retained separately.
This server cannot be deployed
Run and manage AI agent tasks on tavya: create, search and steer tasks, read wikis, call the API.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Chat with your Zihin.ai agents, list them and load platform skills from any MCP client.
