UniGrok · one Grok gateway for every coding agent

Run Grok once on your machine. Point every IDE agent at it. Keep the xAI
credential on the server — never in each editor.

UniGrok is a local-first MCP gateway for
xAI Grok. Cursor, Claude, VS Code, Codex, Antigravity, and
other MCP clients share one Streamable HTTP endpoint:

http://localhost:4765/mcp

It routes across the xAI developer API (metered) and the SuperGrok CLI
subscription (when authenticated), and returns the answer under response
with route / plane / cost metadata.

Current release: v0.6.0.

1. What you get

• Shared @grok / agent tool for every IDE on your laptop
• Server-side credentials (API key and/or CLI OAuth)
• Optional local Core UI for status: http://localhost:4765/ui/
• A habit you can opt into: critique Implementation Plans with Grok before the
  user sees them

Your other projects do not need UniGrok repo folders, contributor trees, or
special mounts.

2. Prerequisites

• Git
• uv
• An MCP-capable IDE
• At least one Grok credential path:
  • xAI API key from console.x.ai, or
  • SuperGrok / Grok CLI device login (subscription)

Docker Desktop is the current packaging path for the shared service. Treat it as
how UniGrok runs on your machine — not as “you are a Docker developer.”

3. Run the gateway (one path)

[!WARNING]
UniGrok is not published on PyPI.
pip install mcp-grok installs an unrelated project; use this GitHub checkout.
There is no real npx unigrok server yet — Docker (or uv + compose) is the install.

Fast path (copy/paste):

git clone https://github.com/djtelicloud/grok-mcp-server.git && cd grok-mcp-server
uv run python main.py init
docker compose up --build -d

init creates .env if missing and prints IDE MCP snippets for
http://localhost:4765/mcp. After the service is healthy, you can close this
repo and work in any project with @grok.

Before checking readiness, complete one credential path:

• xAI API: set the developer key in server .env before starting Compose
  (or rerun docker compose up -d after editing it).
• CLI subscription: after the image is up, run:

docker compose run --rm grok-cli-auth

Then verify the usable plane:

curl --fail -s http://localhost:4765/readyz

You are ready when /readyz reports "status":"ready". /healthz only proves
the process is up; CLI-only installs must authenticate before this readiness
check.

4. Connect your IDE (paste this to your agent)

Copy the block for your IDE from the init output, or paste this prompt to your
local coding agent:

Configure UniGrok MCP for this machine:
- Streamable HTTP URL: http://localhost:4765/mcp
- Send a stable X-Client-ID header for this IDE (e.g. cursor, claude-code, vscode, codex)
- Never put XAI_API_KEY in IDE MCP settings; credentials stay in UniGrok's server .env
- After connecting, call tools/list and grok_mcp_discover_self
- Prefer the UniGrok agent tool when I say @grok or want a second opinion
- When I ask for a multi-step Implementation Plan, get a UniGrok second opinion
  (agent mode thinking or reasoning) and improve the plan before showing it —
  only if I want that habit; do not silently spend metered API credits
- Do not invent a second MCP port, Forge, or land workflow for ordinary use

Detailed multi-IDE notes: docs/ide-setup.md (public path
only; contributor dual-runtime detail lives in CONTRIBUTING).

5. Prove it in 60 seconds

1. Restart the IDE MCP client.
2. Ask: “Call UniGrok discover_self and tell me which credential planes are ready.”
3. Ask for a small plan, then: “Get a UniGrok second opinion on that plan before
   you show me the Implementation Plan.”

Optional status UI (this machine only): open
http://localhost:4765/ui/.

6. Security (short)

1. Keep XAI_API_KEY and CLI OAuth on the UniGrok service — never in IDE configs.
2. API plane is metered; CLI subscription cost is not exposed by the provider —
   UniGrok only tracks local CLI activity.
3. Stable UniGrok does not browse your project unless you pass
   workspace_context.
4. Loopback Core UI is for the machine owner; it is not a public multi-user
   console.
5. Do not paste secrets into chat.

7. Project site (optional)

The public site at https://grokmcp.org is bound to the
existing project repository. It is not an idless installer template. For the
optional contributor control surface, GitHub App OAuth establishes identity
and each privileged request performs a fresh installation-token lookup of
repo role; a Sites rollback fallback remains only for the legacy identity
binding path. That control plane does not replace local UniGrok MCP on
localhost:4765, and it never holds your xAI key.

8. Where docs live

Source of truth: this repo’s docs/okf/ + the site OKF.
GitHub Wiki (optional): human-friendly mirror only, generated from OKF
(see docs/wiki-okf-mirror.md). Do not hand-edit the
wiki as product docs. Empty or stale wiki is not an outage — use OKF.

9. Next steps

Contributors and admins: dual-runtime Forge, landing, Swarm, and insider Console
behavior are documented only in CONTRIBUTING.md — not required
for ordinary use.

License

MIT