Grok Bot MCP

Portable Model Context Protocol server that exposes a Grok Bot tool surface to any MCP-compatible agent — ChatGPT, Claude Desktop/Code, Cursor, and other HTTP or stdio MCP clients.

• Remote clients connect over HTTPS + OAuth 2.1 (Streamable HTTP /mcp).

• Local clients use a stdio bridge to the same loopback MCP (no tunnel).

• General-only mode runs on hosts without Grok Bot: set GROK_BOT_MCP_GENERAL_ONLY=true.

• Workspace tools stay folder-scoped; an optional agent-bridge mailbox talks to other Grok Bot agents.

From Grok Bot, paste the One-phase install prompt below (or run bash start-secure.sh) to launch this MCP and wire agent-bridge. The install asks which MCP client(s) to connect — ChatGPT, Claude, Cursor, Codex, or your own — then gives matching connect steps.

Use cases

What this MCP is for:

1. Give an external AI your Grok Bot workstation — A remote MCP client gets a scoped shell/files/gh workspace on the same machine as Grok Bot, without handing over the whole disk.

2. Orchestrate Grok Bot teammates from outside — Via agent-bridge (list_agents / message_agent / check_replies), a client can ask specialized agents (QA, X, VPS, research, …) and pull replies back into its own chat.

3. End-to-end “agent of agents” pipelines — Example: ChatGPT or Claude plans work → MCP tools edit a repo / open PRs → MCP messages a Grok Bot specialist → results return through check_replies.

4. Local IDE / desktop agents — Claude Desktop, Cursor, or Codex CLI attach over stdio for the same tools without a public tunnel.

5. Secure remote demos — HTTPS + OAuth (owner password / CIMD including private_key_jwt) so the connector is not a No-Auth open URL.

6. Keep secrets and scope on your box — Workspace root is explicit (GROK_BOT_WORKSPACE); credentials stay in gitignored secrets/; mailboxes stay local.

Not a use case by itself: hosting a public unauthenticated filesystem/shell on the internet.

In a real session on September 10, 2026, ChatGPT acted as the coding agent, while Grok Bot MCP provided access to a remote development environment. The work covered ShiningPie's Yarn tooling and the companion ParadiseEngine tray integration. ChatGPT did not hand the implementation to a separate Grok agent and wait for it to solve the task.

The interaction looked like this:

User request
    ↓
ChatGPT: decide the next action and prepare code, patches, or commands
    ↓
Discover tools through api_tool
    ↓
Call Grok Bot MCP tools
    ↓
Remote workspace: files, Git, dotnet, Azure CLI, GitHub CLI
    ↓
Receive file contents, command output, exit codes, or process status
    ↓
ChatGPT: inspect the result, make corrections, and issue the next call

This walkthrough describes the calls and results visible in that conversation, rather than assumptions about Grok Bot's internal implementation. The paths, tool namespaces, process identifiers, and commands below are examples from that session, not required settings for every installation.

1. Discovering the available tools

ChatGPT first used its tool-discovery interface to load Grok Bot's available actions. For example, the following discovery call appeared in the session:

api_tool.list_resources(
    paths=["Grok_Bot_MCP"],
    query="run_script"
)

That call does not execute a script. It discovers the matching functions and their argument schemas. After discovery, ChatGPT can invoke a function such as Grok_Bot_MCP.run_script. The api_tool discovery interface shown here belongs to the ChatGPT client; it is not an MCP protocol method that every client uses.

Earlier turns exposed the connector under Grok_Bot; later turns used Grok_Bot_MCP. Those are the tool namespaces shown in the conversation. The trace alone does not establish whether that naming change corresponds to a different underlying server.

There were repeated discovery calls during the session. These were not repeated clones, builds, or edits—just additional tool discovery. Several were redundant and added overhead.

2. Reading and changing the remote workspace

The repository operations happened under these paths in the environment reached through Grok Bot:

/workspace/chatgpt/ShiningPie
/workspace/chatgpt/ParadiseEngine

ChatGPT used a mixture of dedicated filesystem/Git tools and command execution:

For example, ChatGPT read AGENTS.md, the existing Yarn compiler, launcher build targets, and the native tray implementations before editing them.

ChatGPT supplied the implementation content and edits. The MCP tools applied them to the workspace and returned results such as the number of files written or patches applied. ChatGPT then read files or diffs back to inspect the changes.

The uploaded document's /mnt/data/... path was separate from these remote repository paths. They should not be assumed to refer to the same filesystem.

3. Using run_script as a programmable execution interface

For multi-step operations, ChatGPT sent Python code to run_script. One actual call in the session had the following shape; the script body is omitted here:

Grok_Bot_MCP.run_script(
    language="python",
    cwd="/workspace/chatgpt/ParadiseEngine",
    timeout=120000,
    code="...Python code..."
)

The returned execution records showed commands such as:

python3 /tmp/mcp-script-89a02476a406.py

Inside those scripts, ChatGPT used subprocess.run(...) to invoke Git, dotnet, Azure CLI, and GitHub CLI. This combined related operations, parsed their JSON output, asserted expected results, and stopped when a condition failed.

A concrete example was the concurrency regression check. The script temporarily introduced a lost-edit defect, rebuilt and ran the Coyote tests, required the expected test to fail, restored the original source in a finally block, then rebuilt and required the tests to pass.

That was Python executing a test procedure supplied by ChatGPT, not a natural-language assignment sent to another agent.

4. Running longer commands and checking their results

For builds and test suites, ChatGPT often used start_process. It returned a process identifier and PID, for example:

processId: proc-1789025731562-3079ba9e
pid: 969105

The command could continue executing while ChatGPT made other tool calls. ChatGPT subsequently used read_process or read its redirected log file to determine what happened.

The execution tools returned fields including:

success
exitCode
timedOut
stdout
stderr
startedAt
finishedAt

A successful tool invocation was not sufficient evidence that the build or tests passed. ChatGPT inspected the actual output and test summaries.

This distinction mattered in the session: some commands combined a build with tail to display its log. The shell could return success because tail succeeded even though the earlier build failed. The logs exposed those failures, which were corrected or addressed before rerunning the checks.

5. Accessing Azure DevOps and GitHub through command-line tools

For this workflow, ChatGPT did not use a browser to click through Azure DevOps or GitHub, nor a separate native repository connector. It invoked the tools installed in Grok Bot's environment:

git → fetch, branch, diff, commit, push
az  → Azure DevOps work items and pull requests
gh  → GitHub pull requests and account/repository queries

Examples from the session include:

az repos pr show --id 87 --organization https://dev.azure.com/ShiningPie

and:

gh pr create \
  --repo ParadiseEngine/ParadiseEngine \
  --base main \
  --head feat/tray-task-submenus \
  --title "Add project task submenus to the existing watch tray" \
  --body-file /workspace/chatgpt/ShiningPie/.editor/tray-engine-pr.md \
  --assignee quabug

Those commands used authentication available in that environment. For example, gh api user returned quabug. The complete credential-storage or provisioning mechanism cannot be determined from the visible execution records.

After creating or updating resources, ChatGPT queried them again to verify the saved title, source and target branches, commit, reviewer or assignee, and issue linkage.

6. What this was—and was not

For the ShiningPie implementation work, ChatGPT did not use list_agents, message_agent, or check_replies. Those are a different, agent-messaging workflow from the direct tool execution used here. Their absence from this workflow does not imply that the optional agent bridge is unavailable.

The distinction is:

What happened:
ChatGPT → Grok Bot tool → filesystem/command → result → ChatGPT

What did not happen:
ChatGPT → message_agent("implement this") → another AI develops it independently

The trace also does not reveal the MCP transport configuration, the server's internal architecture, or which physical machine hosts the workspace. It shows the functions invoked and the execution environment's reported results—not a packet-level protocol trace or proof that execution occurred on the user's desktop.

In practical terms, Grok Bot MCP functioned as ChatGPT's remote terminal, file editor, and process interface. ChatGPT directed the development and verification loop; MCP carried out the requested operations and returned their results.

Related MCP server: local-env-mcp

Features

• Workspace tools (via chatgpt-local-mcp): files, shell, git/gh, and related utilities, scoped to GROK_BOT_WORKSPACE

• OAuth 2.1 gateway: DCR + PKCE, owner-password consent; unauthenticated public /mcp → 401

• Cloudflare tunnel in front of the gateway only (quick tunnel by default; optional named tunnel token for a stable hostname)

• stdio bridge (start-stdio.sh): Claude Desktop / Cursor command transport → http://127.0.0.1:3851/mcp

• Agent bridge: list_agents, message_agent, check_replies for teammate messaging (optional webhook for faster outbox notify)

• npm run doctor: readiness checks against the live stack

Structured action results

Every action returned by tools/list includes a JSON outputSchema: 53 workspace actions in general-only mode, or 56 with the three agent-bridge actions enabled. The runtime advertises MCP protocol version 2025-06-18, which supports structured tool results.

Successful tools/call responses contain the action's result object in result.structuredContent. The existing result.content[0].text still contains the same object serialized as JSON, so clients that consume the text payload do not need to change their result parsing. Clients must support the advertised protocol version.

Schemas describe the action result, not the surrounding JSON-RPC or MCP envelope. Dates are strings; absent JavaScript values are omitted rather than converted to null. Contracts cover per-file batch errors, managed-process lifecycle fields, all git_branch actions, and optional agent metadata. json_query.result intentionally accepts arbitrary JSON, and parent-supplied inbox records retain custom metadata.

Thrown tool errors retain the standard isError: true text response without fabricated success-shaped data. A completed command with a nonzero exit code still returns its normal structured command result with success: false.

Workspace contracts live in runtime/src/output-schemas.js; agent contracts are defined alongside their tools in agent-bridge/mcp-tools.js. Registration fails if an action has no object output schema. When adding or changing an action, update its schema and contract tests together:

npm ci --prefix runtime --no-audit --no-fund
npm test

The tests compile every advertised schema and validate real action responses, including partial results and errors. Files, repositories, managed processes, and agent mailboxes are isolated fixtures; browser and clipboard operations use test doubles. Ajv is a development-only dependency, not part of the production runtime.

Requirements

• Node.js 20+

• cloudflared (for remote HTTPS; start-secure.sh will locate or download linux-amd64 if missing; not needed for stdio-only)

• Optional: ChatGPT Developer Mode, Claude Desktop, Cursor, or any MCP client

Quick start

git clone git@github.com:quabug/grok-bot-mcp.git
cd grok-bot-mcp
npm install
(cd oauth-gateway && npm install)   # first time, for OAuth gateway
(cd runtime && npm install)         # first time, for HTTP MCP server

Remote HTTP + OAuth (ChatGPT and other HTTPS MCP clients)

bash start-secure.sh
# or: npm run start:secure

Public base URL is written to secrets/PUBLIC_BASE_URL.txt (gitignored). Point the client at:

• URL: https://<tunnel>/mcp

• Auth: OAuth

Complete the consent page with the owner password from secrets/OWNER_PASSWORD.txt (never commit this file). See examples/chatgpt-connector.md.

Stable hostname (recommended for production):

export CLOUDFLARE_TUNNEL_TOKEN='...'          # from Cloudflare Zero Trust → Tunnels
export GROK_BOT_PUBLIC_BASE_URL='https://mcp.example.com'
bash start-secure.sh

Or if ingress is already provided externally:

export GROK_BOT_PUBLIC_BASE_URL='https://mcp.example.com'
export GROK_BOT_SKIP_QUICK_TUNNEL=1
bash start-secure.sh

Stop:

bash stop-secure.sh

Do not use start.sh for public exposure. Prefer start-secure.sh.

Cloudflare quick tunnels change URL on restart — update remote connectors, or use a named tunnel token as above.

General tools only (hosts without Grok Bot)

Set GROK_BOT_MCP_GENERAL_ONLY=true to run on a regular development machine without Grok Bot, agent profiles, or a parent agent routine:

export GROK_BOT_MCP_GENERAL_ONLY=true
export GROK_BOT_WORKSPACE="$HOME/projects"
bash start-stdio.sh
# For remote HTTPS + OAuth instead:
# bash start-secure.sh

This mode identifies itself as Workspace MCP and retains the general file, shell, Git, process, network, and utility tools. It does not load the agent bridge, create its mailboxes, or start its notification listener. list_agents, message_agent, and check_replies are neither listed nor callable. The existing workspace scope and authentication settings still apply.

For desktop client configs, add "GROK_BOT_MCP_GENERAL_ONLY": "true" to the command's env object. The option also works when running node runtime/src/server.js directly (including from runtime/.env). Direct launches still need explicit workspace, host, port, and authentication configuration; the startup scripts set these for loopback use.

The default is false, preserving the Grok Bot agent tools. Only true and false are accepted. Restart the MCP server when changing modes and refresh the client's tool list. The stdio launcher rejects reuse of a server running the other mode; stop that server or select a different GROK_BOT_MCP_PORT. Run GROK_BOT_MCP_GENERAL_ONLY=true npm run doctor for remote-stack checks that expect general tools and skip agent notification/mailbox checks.

Local stdio (Claude Desktop, Cursor, …)

No tunnel or OAuth required. The bridge talks to loopback MCP only:

bash start-stdio.sh
# or: npm run start:stdio

Example configs (replace /ABS/PATH/TO/...):

• examples/claude_desktop_config.json

• examples/cursor-mcp.json

ALLOW_NO_AUTH_LOCAL=1 / AI_PC_MCP_ALLOW_NO_AUTH=true apply on loopback so stdio clients skip OAuth. Remote HTTPS still requires the OAuth gateway.

Doctor

npm run doctor
# or: bash doctor.sh

Checks Node version, deps, ports 3851/3860/3861, MCP tools/list (agent tools), gateway 401 without auth, secrets file presence (not contents), cloudflared, outbox pending count, and optional webhook config. Exits non-zero on hard failures.

Docker

The image runs the HTTP MCP server in general-only mode by default, as the unprivileged node user (UID/GID 1000). It includes Node.js 22, Python 3, Git, GitHub CLI, curl, and zip utilities. Tools operate inside the container; mount the folder you want them to access at /workspace.

docker build -t grok-bot-mcp:local .
docker run --rm --init --name grok-bot-mcp \
  -p 127.0.0.1:3851:3851 \
  --mount "type=bind,source=$PWD,target=/workspace" \
  grok-bot-mcp:local

Connect an HTTP MCP client to http://127.0.0.1:3851/mcp. Health is available at http://127.0.0.1:3851/health. On Linux, ensure the mounted folder is writable by UID 1000, or run with --user "$(id -u):$(id -g)" to match its ownership. Project-specific SDKs and dependencies can be added in a derived image.

The image runs the raw HTTP runtime; it does not include the OAuth gateway or Cloudflare tunnel. Keep the published port on loopback as shown. Remote access requires an authenticated HTTPS gateway in front of this container.

To opt into Grok Bot agent tools, pass -e GROK_BOT_MCP_GENERAL_ONLY=false, mount agent profiles read-only, and set GROK_BOT_AGENTS_DIR and GROK_BOT_SELF_AGENT_ID. Persist the mailbox directories under /app/agent-bridge/{outbox,inbox,sent} on writable mounts and arrange parent delivery as described in Agent bridge.

Publishing versioned images

The Docker workflow tests the runtime and builds and smoke-tests the image on pull requests. Pushing a tag in the exact form vMAJOR.MINOR.PATCH, such as v0.1.2, also publishes an AMD64/ARM64 image to GitHub Container Registry after those checks pass:

# After committing and pushing the release changes:
git tag v0.1.2
git push origin v0.1.2

That release publishes these tags:

• ghcr.io/quabug/grok-bot-mcp:v0.1.2

• ghcr.io/quabug/grok-bot-mcp:0.1.2

• ghcr.io/quabug/grok-bot-mcp:latest

latest follows the most recently published release. The image version comes from the Git tag; changing package.json is not required. The MCP protocol server version remains the value in runtime/src/server.js. The workflow uses GITHUB_TOKEN with packages: write; no registry password secret is needed. To allow anonymous pulls, set the GHCR package visibility to Public after the first publication.

docker pull ghcr.io/quabug/grok-bot-mcp:v0.1.2

Environment

Agent bridge

The MCP process cannot call Grok Bot’s SendToAgent directly. It writes an outbox; the parent Grok Bot agent must deliver and write replies into the inbox. See agent-bridge/PARENT.md.

Faster notify (optional): set AGENT_BRIDGE_WEBHOOK_URL or put the URL on the first line of agent-bridge/webhook.url (gitignored). On each message_agent, the bridge POSTs JSON {event:"outbox", id, to_agent_id, to_name} fire-and-forget.

Mailbox (gitignored live data): agent-bridge/outbox/, sent/, inbox/.

Layout

grok-bot-mcp/
  runtime/           # local MCP HTTP server (branded Grok Bot)
  oauth-gateway/     # OAuth 2.1 front door for remote /mcp
  agent-bridge/      # mailbox + MCP tool module + parent helpers
  bin/stdio-bridge.js
  start-secure.sh    # HTTPS + OAuth (remote)
  start-stdio.sh     # stdio bridge (local)
  stop-secure.sh
  doctor.sh          # readiness checks
  examples/          # Claude / Cursor / ChatGPT client snippets
  secrets/           # gitignored — passwords, public URL

Security

• Loopback-only MCP; public traffic hits OAuth first

• Owner password gates consent; prefer storing only the bcrypt hash long-term

• Workspace tools are folder-scoped — treat the tunnel + password as highly sensitive

• Never commit secrets/, live mailboxes, tokens, or downloaded cloudflared binaries

Before you publish / known issues

Fixed in-repo (this release)

1. Faster outbox notify — optional webhook (AGENT_BRIDGE_WEBHOOK_URL / agent-bridge/webhook.url) fires on message_agent (still needs a parent to SendToAgent).

2. Configurable agents dir / self id — GROK_BOT_AGENTS_DIR, GROK_BOT_SELF_AGENT_ID.

3. add-reply.sh resolves names → UUID — from_agent_id stored as UUID when found in agents.json.

4. cloudflared discovery / download — PATH, ~/.local/bin, npm paths; can fetch linux-amd64 into gitignored bin/cloudflared.

5. Stable tunnel support — CLOUDFLARE_TUNNEL_TOKEN + GROK_BOT_PUBLIC_BASE_URL, or skip quick tunnel when external ingress is already set.

6. npm run doctor / doctor.sh — hard checks for Node, deps, ports, agent tools, gateway 401, secrets presence.

Still operator-dependent

1. Named Cloudflare tunnel token — create a tunnel in Cloudflare Zero Trust, set CLOUDFLARE_TUNNEL_TOKEN + GROK_BOT_PUBLIC_BASE_URL. Quick tunnels still rotate on restart.

2. ChatGPT reconnect — after tool list changes, Disconnect → Reconnect the connector (re-consent) or ChatGPT may keep a stale tool cache without list_agents / message_agent / check_replies.

3. Parent routine + webhook URL — MCP only queues mail. Wire a Grok Bot routine (and preferably a webhook that wakes it) to deliver outbox → SendToAgent and add-reply for inbox. Without that, message_agent appears to hang.

4. OAuth owner password — under secrets/ (gitignored). Treat like a root password; rotate; never paste into chat/git.

5. Workspace scope — point GROK_BOT_WORKSPACE at an intentional folder; do not use --bypass for shared tunnels.

6. High privilege tools — shell + file write + gh mean a stolen OAuth session is serious. Keep the connector private.

7. Client differences — ChatGPT remote = HTTPS + OAuth. Claude / Cursor often prefer stdio (start-stdio.sh).

8. Repo hygiene — keep secrets/, mailboxes, STATUS.txt, webhook.url, and binaries out of git.

One-phase install (paste into Grok Bot)

One phrase you can send:

Install and run https://github.com/quabug/grok-bot-mcp, wire agent-bridge to my other Grok Bot agents, ask me which MCP client(s) to connect, then finish setup for those clients.

Full one-phase prompt (copy the whole block):

ONE-PHASE SETUP: Grok Bot MCP + agent-bridge + chosen MCP client(s)

Repo: https://github.com/quabug/grok-bot-mcp (private; use gh as the logged-in GitHub user).

Goal: Install the MCP on this machine, wire agent-bridge so *any* connected MCP client can message my other Grok Bot agents, then finish connect steps only for the client(s) I choose.

Before connecting a client, ASK ME which MCP client(s) to set up. Offer choices (multi-select OK) and allow a custom answer:
- ChatGPT (HTTPS + OAuth connector)
- Claude Desktop / Claude Code (usually stdio)
- Cursor (stdio or HTTP)
- Codex / Codex CLI
- Other (I will type the agent/product name and preferred transport: HTTPS+OAuth or stdio)

Do not assume ChatGPT. If I pick several, cover each. If I type my own, adapt steps to that product.

Then do:

A) Install & run MCP
1. Clone if missing (prefer /workspace/grok-bot-mcp or ~/grok-bot-mcp). Export GROK_BOT_MCP_ROOT.
2. Workspace folder for tool scope (prefer /workspace/chatgpt or $GROK_BOT_MCP_ROOT/../chatgpt). Export GROK_BOT_WORKSPACE. Set GROK_BOT_SELF_AGENT_ID to this agent's id; GROK_BOT_AGENTS_DIR if needed.
3. npm install at repo root; npm install in oauth-gateway/ and runtime/.
4. Start transport appropriately:
   - If any chosen client needs a public HTTPS URL → bash start-secure.sh (named tunnel token if available; else quick tunnel).
   - If only local stdio clients → bash start-stdio.sh may suffice (still fine to run start-secure.sh if I also want remote later).
5. npm run doctor; fix hard failures.
6. Confirm secrets paths exist when using HTTPS (PUBLIC_BASE_URL.txt, OWNER_PASSWORD.txt mode 600). Never commit secrets or paste the password into chat/git — report file paths only.

B) Wire other Grok Bot agents (agent-bridge) — always
7. Create/update routine "Grok Bot MCP agent-bridge" (webhook and/or @every 5m):
   - Flush outbox with SendToAgent (preface: relayed via Grok Bot MCP from the external client), then mark-sent.sh
   - On bridged [agent] replies: add-reply.sh so check_replies works
   - Stay quiet when outbox empty
8. Save routine Webhook URL to agent-bridge/webhook.url when available; soft-reload MCP without needlessly rotating the tunnel.
9. Smoke agent tools: list_agents / message_agent / check_replies.

C) Finish only for my chosen client(s)
10. Report MCP URL (if HTTPS), Auth mode, password file path (not value), routine/webhook status, doctor result.
11. Give short connect steps **only for the client(s) I selected** (and the custom one if any). Include reconnect-after-tool-change notes where that client caches tools.
12. Reuse running PIDs/URLs when possible. Never expose No-Auth on a public URL.

License

MIT © 2026 quabug