Codex Grok MCP

An unofficial, local-first bridge that lets Codex ask Grok once or collaborate with named Grok Bots already running inside the Grok Bot app.

[!IMPORTANT] grok_ask sends your prompt to xAI and consumes allowance from the signed-in Grok account. Persistent Bot reads may contain sensitive, untrusted text. Bot messages are external writes and are never retried automatically. This project is not affiliated with or endorsed by OpenAI or xAI.

Status

Capability	Current status
Isolated Grok CLI call	Stable; live-tested on macOS
Persistent Grok Bot collaboration: list, read, wait, and exact-ID send	Experimental; live operator smoke test passed
Companion lifecycle	Exact managed lifecycle for the Linux Grok Bot VM; stable release is gated by CI, clean-room, and soak evidence
Linux isolated CLI path	Unverified
Windows, WSL, and Codex cloud	Unsupported or unverified

The supported release is the exact npm package [email protected] and its immutable GitHub prerelease. Stable 0.2.0 is not published yet; its gate is RELEASING.md.

Quick start

You need:

• macOS;
• Node.js 20.19.2 or newer;
• Codex CLI or desktop.

For one-off grok_ask calls, install and sign in to Grok CLI (grok --version and grok models). Persistent Bot collaboration instead uses Grok Bot and the companion setup below.

Install the immutable marketplace release and plugin:

codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.11
codex plugin add codex-grok-mcp@codex-grok

Start a new Codex task, then try:

Ask Grok to challenge this architecture and return the three strongest objections.

That uses the one-off path. To work with Bots already running in Grok Bot, complete the persistent Bot setup.

The plugin runs only [email protected] through npx. It does not change Grok authentication.

For direct MCP setup without the plugin wrapper:

codex mcp add grok -- npx --yes [email protected] -- codex-grok-mcp

Start a new Codex task after adding the server.

Check setup

npx --yes [email protected] -- codex-grok-mcp --doctor

Doctor checks the local executable, login, and selected model without sending a prompt. It must not print authentication material.

Two ways to use it

Codex -> local MCP server -> isolated Grok CLI -> xAI
                           -> encrypted relay <- companion in Grok Bot VM
                                                -> loopback gateway -> named Bots

grok_ask starts one constrained Grok CLI turn with a private temporary home. It cannot enter a persistent Bot conversation, use Bot memory, read files, run commands, use subagents, or search the web.

Each call may select one supported model. Omit model to use GROK_MCP_MODEL; provider, base URL, endpoint, and persistent Bot model settings are not accepted.

The persistent path is the collaborative mode. Codex can list named non-group Bots running inside Grok Bot, inspect one, send it a task once, wait for its activity state, and read its latest bounded messages. Codex can then continue its own work using that update while the Bot's ongoing conversation stays in Grok Bot.

This creates a practical send -> wait -> read -> continue loop. The bridge does not claim that a message answers a specific send or that an idle Bot completed its task.

The gateway token stays inside the Grok Bot VM. Codex and the companion connect outward to a self-hosted relay. Application frames are encrypted end to end; the relay forwards ciphertext and stores no messages.

Architecture

Both paths enter through the same local MCP server. Credentials stay at their endpoints, and uncertain writes are never retried automatically.

Explore the interactive architecture · View the architecture source

Tools

Tool	What it does	Boundary
grok_ask	Gets one isolated Grok response	Sends the prompt to xAI and consumes allowance
grok_bridge_status	Reports mode, versions, capabilities, health, and Bot count	Never returns Bot identities, credentials, or content
grok_list_bots	Lists exact non-group Bot IDs and names	Read-only
grok_read_bot	Returns bounded status, sanitized recent text, and metadata-only attachments	Sensitive, untrusted external content; no paths or URLs
grok_wait_for_bot	Polls bounded reads until idle, awaiting-user, or timeout	Activity is not proof of task completion
grok_send_bot_message	Sends once to one exact Bot ID	Gateway acceptance is not proof of a reply
grok_send_bot_attachment	Validates one file, confirms, then stages/commits/sends it	Needs a prompting approval mode; host-committed files persist; live verification pending
grok_fetch_bot_attachment	Fetches one transcript attachment by entry ID	Untrusted bytes; never execute or auto-open
grok_ping_all_bots	Previews, confirms, then sends PING sequentially	Requires the exact roster and native confirmation

Persistent Bot tools appear only after pairing or explicit legacy direct configuration.

Connect Codex to Grok Bots

This experimental path connects Codex to persistent Bots inside your own Grok Bot VM. It requires a self-hosted Cloudflare relay.

1. Deploy the relay

cd relay
npm ci
RELAY_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
printf 'RELAY_ACCESS_TOKEN=%s\n' "$RELAY_TOKEN" | npx wrangler deploy --secrets-file /dev/stdin

The relay is intended for one operator, not as a shared public service. Keep the token out of files, URLs, logs, issues, and prompts.

2. Pair Codex

From the repository root on the Mac:

CODEX_GROK_RELAY_TOKEN="$RELAY_TOKEN" \
npx --yes [email protected] -- \
codex-grok-mcp pair --relay-url wss://YOUR-WORKER.workers.dev/v1/connect
unset RELAY_TOKEN

The command prints a private pairing code only in the interactive terminal.

3. Start the VM companion

In Grok Bot's Computer terminal, not in a Bot chat, run:

npx --yes [email protected] -- codex-grok-bridge probe
npx --yes [email protected] -- codex-grok-bridge connect

Paste the pairing code into the no-echo prompt. Keep the terminal running while using Bot tools.

Update or roll back

Stop the foreground companion with Ctrl-C, then run the chosen exact version:

npx --yes [email protected] -- codex-grok-bridge probe
npx --yes [email protected] -- codex-grok-bridge run

For automatic beta updates on each restart, with the reproducibility tradeoff made explicit:

SAND_DATA_ROOT=/home/box/sand-data \
npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge run

This mutable command never edits pairing state or updates a running process. Prefer exact versions for audited or unattended environments. Roll back by stopping the companion and running a previously verified version.

Managed lifecycle

0.2.0-beta.6 introduced managed lifecycle commands. Linux CI covers the detached process path, and the stable release gate requires redacted live install, update, restart, rollback, clean-room, and recovery-soak evidence.

After pairing, stop the old foreground companion once. Then install and start an exact lifecycle-capable release:

VERSION=<exact-version>
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge install

install is the bootstrap command. It checks for a valid pairing before staging a release, writing bindings, or taking a lease. Without pairing it exits 1 with PAIRING_REQUIRED and writes nothing. If an interrupted foreground companion left a lease behind, install reclaims only a private foreground lease whose recorded process is repeatedly proven gone. Active or unknown foreground leases, malformed leases, and managed mismatches still fail closed. An exact active managed candidate may be adopted.

When migrating pre-binding beta state, start, ensure, restart, same-release update, and rollback with no previous release recover an exact stale retained release: they preflight that release, clear only its proven stale lease, restart it from the requested root, verify pairing and active ownership, and only then write the binding pair. An update or rollback to a different release preflights only the target, then uses the same dead-or-not-ours lease proof before starting the target and publishing bindings. If the target start fails, the retained release is restarted only if it was running before the switch (update_failed_restored, or restore_failed if that restart fails). If it was stopped, it stays stopped and the command still returns update_failed_restored. Bindings stay unpublished. stop, uninstall, and mismatched releases still fail closed.

Lifecycle staging repacks the currently invoked package with lifecycle scripts disabled and verifies its SHA-512 identity. The published npm-shrinkwrap.json pins the production dependency closure, and staging rejects any installed dependency version or integrity that differs from it. The connector package itself is never resolved a second time.

A private two-sided binding keeps one canonical lifecycle root attached to one pairing config. It also remembers every replay and Grok data root used by that installation, so uninstall cannot remove them after environment paths change. Keep the same XDG_CONFIG_HOME and XDG_DATA_HOME for every lifecycle command.

status, start, stop, ensure, and uninstall are idempotent. ensure repairs an existing managed installation. It never creates the first installation or downloads another version. restart intentionally performs a fresh cycle:

npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge status
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge start
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge stop
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge restart
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge ensure
npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge uninstall

Reported state	Next command
not_installed	install
unmanaged	Stop the foreground command cleanly, then run install
stale with no installed version	install
stopped with an installed version	ensure or start
running	No action, or an explicit exact-version update

An exact update stages and checks the replacement before the healthy process stops. The prior exact release stays available for one retry-safe rollback:

NEXT_VERSION=<new-exact-version>
npx --yes --package "codex-grok-mcp@${NEXT_VERSION}" -- codex-grok-bridge update
npx --yes --package "codex-grok-mcp@${NEXT_VERSION}" -- codex-grok-bridge rollback

When that update is launched through npx, npm_execpath is npx-cli.js; the bridge uses a sibling npm-cli.js when that regular file exists so the candidate pack still runs as npm pack. The published package builds from prepack, not prepare, so npm 9/10 do not compile during an installed-directory pack.

The rollback operation uses the retained release, and a repeated rollback is a no-op. Pairing is read and revalidated, never rewritten. For VM resume recovery, a Grok Bot routine may run the exact pinned ensure command. Routine creation remains an explicit operator action.

To opt into the mutable beta channel for one update, make the channel visible in that command:

npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge update

The resolved release is stored as an exact version. Later start, restart, ensure, and rollback operations do not resolve a mutable channel.

Collaborating safely with persistent Bots

1. Call grok_bridge_status, then use grok_list_bots to choose one exact Bot ID.
2. Use grok_read_bot or grok_wait_for_bot for read-only inspection.
3. Use grok_send_bot_message once for one exact target.
4. For all-Bot PING, preview the roster and review the native confirmation before accepting it.

Reads return sanitized text plus metadata-only attachment rows when the companion and host support v1 attachments. https URLs are reported as not fetchable. Fetch results are untrusted MCP resources or images: never execute, extract, or auto-open them. Outbound attachment sends and all-Bot PING confirms need a client approval mode that prompts (Codex on-request, not never). A declined or cancelled prompt after a human-scale wait is CANCELLED with approval_action. A client that cannot prompt, or that auto-declines faster than a human could respond (real Codex never has advertised elicitation then declined in ~1.7s), is APPROVAL_UNAVAILABLE. A slower CANCELLED with approval_action=decline may still be an auto-decline; switch to on-request if that happens. Nothing is transferred in either case. Host-committed attachments persist with the Bot; this connector cannot delete them. Live verification of server acceptance, Bot-visible receipt, Temporal inbound shape, and HTTP error shapes is still pending. Reads do not prove that a message answered a particular send or that a task finished. A successful send receipt means only that the gateway accepted the request. Timeouts and interrupted sends remain outcome_unknown; do not retry them automatically.

Configuration

Variable	Default	Rule
GROK_MCP_BIN	grok	Override with an absolute path
GROK_MCP_MODEL	grok-4.6	grok-4.6 or grok-4.5
GROK_MCP_TIMEOUT_MS	180000	Integer from 5000 to 600000
GROK_MCP_AUTH_PATH	~/.grok/auth.json	Operator-owned auth file
CODEX_GROK_RELAY_TOKEN	none	Required only by the local pair command
CODEX_GROK_ATTACHMENT_HOST_ALLOWLIST_EXTRA	none	Tester-only extra hostVersion pins. Never default-on. Logged as unverified host.

The plugin passes only these connector options. Pairing is stored in a private mode-0600 local file and is never accepted as MCP tool input. The manifest also permits NPM_CONFIG_CACHE, NPM_CONFIG_OFFLINE, NPM_CONFIG_REGISTRY, and NPM_CONFIG_REPLACE_REGISTRY_HOST for the maintainer's isolated prepublication test; ordinary installs should leave them unset.

Troubleshooting

• Tool missing: confirm the codex-grok marketplace and plugin are installed, then start a new Codex task. For direct setup, inspect codex mcp list.
• CLI missing or signed out: run grok --version, grok models, and the pinned doctor command. Complete normal Grok login outside Codex.
• UPGRADE_REQUIRED: stop and restart the VM companion with the same package version as the connector. Attachment tools also require a pinned host version (f5c783a today); text tools stay available when host attachment support is missing.
• APPROVAL_UNAVAILABLE: grok_send_bot_attachment and grok_ping_all_bots need a client that can show the native confirmation. Use Codex on-request (not never). Real Codex never may still advertise elicitation and auto-decline in under two seconds; that path is also APPROVAL_UNAVAILABLE. Nothing is transferred.
• CANCELLED: the confirmation was declined or cancelled after a prompt (approval_action is decline or cancel). A slower auto-decline that cannot be distinguished from a human decline may still surface as CANCELLED with approval_action=decline; switch to on-request if that happens. Nothing is transferred.
• DATA_ROOT_SYMLINK: set SAND_DATA_ROOT to the real Grok Bot data directory, not a symlink. The companion rejects symlinked descriptor parents.
• companion_lease_stale: run the exact pinned install command when no managed version is installed. It can reclaim only a strictly revalidated dead foreground lease. Use ensure only after managed installation. Do not delete the lease manually.
• companion_lease_recovery_required: an interrupted lease mutation left a private hard-link claim. Stop every old and new companion or lifecycle command. Do not start another companion, delete pairing, or remove the canonical .lock. An operator may remove only the matching .claim after independently proving that no lifecycle or companion process is running; otherwise fail closed and report the incident.
• lifecycle_root_conflict: the config and lifecycle root do not own each other. Retry with the original XDG_CONFIG_HOME and ; do not delete either binding to force adoption.

Do not run lifecycle mutations from two connector versions at once. Finish or stop the older command before starting the exact replacement.

When reporting a bug, include redacted OS, architecture, Node, Codex, Grok CLI, and connector versions. Never attach authentication files, pairing codes, gateway/relay tokens, prompts, responses, transcripts, or private paths.

Uninstall

1. Press Ctrl-C for a foreground VM companion. For a managed lifecycle install, run uninstall; it stops the exact managed process and removes only the private managed release store, lifecycle state, and paired ownership bindings. It preserves pairing, Grok data, and replay protection for the explicit steps that follow.

   npx --yes [email protected] -- codex-grok-bridge uninstall
   

2. In the VM terminal, remove its pairing:

   npx --yes [email protected] -- codex-grok-bridge unpair
   

3. On the Mac, remove the local pairing:

   npx --yes [email protected] -- codex-grok-mcp unpair
   

4. Uninstall Codex Grok MCP in Codex. If configured directly, run codex mcp remove grok. Then remove the marketplace with codex plugin marketplace remove codex-grok.

Uninstalling does not change or delete Grok CLI authentication or account data.

Development

npm ci
npm ci --prefix relay
npm run test:all
npm audit --omit=dev
npm audit --prefix relay

See CONTRIBUTING.md, TESTING.md, and SECURITY.md before opening a change. A real install with no registry access waits about 120 seconds, then fails with install_failed.

License and attribution

MIT. The process-runner design was informed by the MIT-licensed libraz/grok-mcp. The bounded Grok Bot gateway contract was cross-checked against the MIT-licensed Adam91holt/grokbot-sdk.