One Grok teammate. Every coding agent.

Install UniGrok once, connect every MCP-capable IDE, and use @grok from any project. Your Grok login and optional xAI API key stay inside one local service — not scattered through editor settings.

http://localhost:4765/mcp

Approved collaborators can also use the owner-operated hosted pilot at https://mcp.grokmcp.org/mcp. It uses browser OAuth and never asks an IDE for an xAI key. Local Compose remains the private, persistent default; see Authenticated remote deployment for the different hosted security and state contract.

_{The local Control Center at http://localhost:4765/ui/ — live routing, cost, and benchmark receipts.}

Get running in three minutes

You need Docker Desktop and Git, plus Grok access. UniGrok runs on two Grok planes, in this order:

1. Grok Build subscription — the default, flat-rate plane. This is all you need.
2. xAI developer API key (console.x.ai) — optional, metered; adds vision, image/video, X search, and silent failover.

Set up plane 1 to get going; add plane 2 whenever you want the extras.

In a hurry? npx @djtelicloud/unigrok prints these setup steps in your terminal. (A full launcher that runs the setup for you is planned; today UniGrok installs via Docker, below.)

1. Download and build

git clone https://github.com/djtelicloud/grok-mcp-server.git
cd grok-mcp-server
docker compose build

2. Connect Grok

Grok subscription (recommended). Log in once — the device-login runs inside the container and stores the session in a private Docker volume:

docker compose run --rm grok-cli-auth

Want the Grok CLI on your own machine too? It is optional:

curl -fsSL https://x.ai/cli/install.sh | bash

xAI API key (optional, metered). Adds vision, image/video, and silent failover. Keep the key in the service owner env only — never IDE MCP JSON, never a second SoT under src/. Factory GroundCommand uses the monorepo Ground key home (parent .env / KEY_HOMES.md); generic installs can export XAI_API_KEY or use docker compose --env-file <private-env>.

Allowed inference env names (first non-empty wins): XAI_API_KEY, XAI_API_KEY_SKY_INFERENCE, XAI_API_KEY_GROUND, XAI_API_KEY_UNIGROK_GROUND (never management / Cursor tokens).

Either CLI login or API key works alone; set both if you want everything.

3. Start UniGrok

docker compose up -d grok-mcp
curl --fail --silent http://localhost:4765/readyz

You are ready when the response says "status":"ready".

New to Grok-powered coding? Cursor (referral link) is an easy on-ramp — set up a Grok plane above whenever you're ready.

Connect your IDE

Paste this into Cursor, Claude Code, VS Code, Codex, Antigravity, or any MCP-capable coding agent:

Configure an MCP server named grok for this machine.

- Transport: Streamable HTTP
- URL: http://localhost:4765/mcp
- Send a stable X-Client-ID header for this IDE, such as cursor or claude-code
- Never place XAI_API_KEY in the IDE configuration; credentials stay in UniGrok
- Reload MCP servers, then call grok_mcp_discover_self
- Use UniGrok's agent tool whenever I say @grok

The config filename varies by IDE, but every client connects to the same local URL.

Hosted pilot (approved collaborators)

For an OAuth-capable MCP client, use this resource instead:

https://mcp.grokmcp.org/mcp

Do not add an API key or hand-written bearer. The client follows the protected-resource metadata, opens Control OAuth, and receives only the scopes the operator approves. Authorization policy can still deny access. The hosted plane is API-only, tenant-scoped, and currently uses instance-local state; it is a collaboration pilot, not anonymous SaaS.

Try it in 60 seconds

Start a fresh conversation in any project and try:

@grok research the best current approach for this feature, then give me a short plan.

@grok remember that this project prefers small modules and tests before refactors.

@grok continue session "my-project" and challenge the implementation plan.

That is it — type @grok, and UniGrok picks the route, model, effort, and recovery for you. Every answer comes back with a plane and cost receipt.

Why vibe coders use UniGrok

What's new in 1.1

Levels that scale with the job

Pass a level when you care how hard Grok thinks:

• none → minimal → low → medium → high → xhigh — one call, native Grok efforts
• max — a silent deep-reasoning harness under the hood
• ultra — a parallel hive: draft, persona votes, then a merge

Leave level unset and UniGrok picks the rung for you. In local Compose, unclear tasks use CLI-first router votes. Hard tasks auto-engage deeper reasoning; a typo fix never pays for a swarm. Receipts expose any bounded API fallback used when those votes are inconclusive.

Jobs that survive restarts

On persistent local Compose, Mission V2 tasks keep their mission ledger across service restarts and resume with the same continue_token; terminal reattach returns the durable winner without rerunning the model. Generic durable jobs keep results recorded before restart. If a generic job was interrupted before a result was recorded, it returns lost: the provider outcome is unknown, so inspect state before retrying a metered or mutating operation.

A gateway that optimizes itself, honestly

The dogfood loop lets the hive rewrite the gateway's own functions — but a rewrite ships only when it is proven behavior-identical and measured >8% faster, with no new imports and a bounded diff. Six functions shipped this way (up to +52.8% measured). Sub-noise "wins" are rejected on principle.

Two Grok planes, one simple entry point

This routing section describes local Compose. The authenticated hosted pilot disables the CLI plane and uses the metered API only.

Need an explicitly selected helper when the network is unavailable? The optional local-model helper runs as a separate, default-off MCP server. It is not a third @grok plane and never activates on an authentication or provider failure.

flowchart TD
    T["{ task: Your request }"] --> L["Live-discovered Grok lead"]
    L -->|"answer / research / reasoning"| D["Direct Grok work"]
    L -->|"lead-authored code brief"| C["Discovered Grok Build specialist"]
    L -->|"lead-authored media brief"| M["Provider image / video specialist"]
    D --> R["Result + model / plane / cost receipt"]
    C --> R
    M --> R

• agent makes web, X search, and code tools available by default.
• The live Grok subscription default leads every request and writes specialist briefs.
• UniGrok selects models, planes, reasoning effort, and recovery automatically.
• Clear tasks route heuristically; otherwise three bounded, CLI-first intent votes select shape. If too few votes parse, an API semantic fallback may run (256 output tokens by default, configurable from 64–1024). Direct work remains subscription-first; specialists and bounded recovery use API as needed.
• Supplying XAI_API_KEY is the service owner's opt-in to API use.
• Set UNIGROK_ENABLE_METERED_API=false for an immediate API kill switch.

Install once, keep projects clean

UniGrok is a global local service. It does not copy itself into every repository and it never receives hidden access to your workspace.

On first use, UniGrok can offer an optional host-native integration pack through grok_mcp_onboard_client:

MCP connects → install globally? → IDE previews owned files → user approves → reload
                                      ↓
                         project guidance still overrides it

• Global is recommended: install a namespaced skill/plugin in the IDE's user scope.
• Project creates only a plan for project-local guidance.
• Not now and Never ask again are explicit choices.
• UniGrok never writes these files itself. The calling IDE uses its normal permissions, shows conflicts, and must not overwrite user-modified files blindly.

The current project-guidance conventions are:

AGENTS.md
.agents/rules/<rule-name>.md
.agents/workflows/<workflow-name>.md
.agents/skills/<skill-name>/SKILL.md

Project customizations take priority over the global UniGrok baseline. UniGrok provides the instructions and templates but remains workspace-neutral.

Safe by design

• The service binds to 127.0.0.1 by default.
• CLI OAuth and the xAI API key stay on the server side.
• The CLI runs in an empty disposable workspace with local file, shell, Git, edit, external MCP, memory, and subagent access disabled.
• Project text reaches Grok only when the calling IDE deliberately sends bounded workspace_context.
• Local durable payloads are recursively secret-redacted before SQLite storage. Mission answer projections are additionally capped at 100 KB.
• Named-session turns and context packs are written only after Mission V2 CommitDone; rejected drafts never enter session memory, and repeated terminal reattach is idempotent.
• In persistent local Compose, terminal runtime rows default to 24-hour retention (configurable 1–720 hours), while named sessions and remembered facts persist until explicitly deleted. Hosted state is instance-local as documented below.
• Media accepts public HTTPS URLs; uploads accept caller-supplied bytes, never local filesystem paths.
• Ask for an image or video without an API key and UniGrok says so plainly — it never fabricates a media link.

See SECURITY.md for the complete public runtime boundary.

Go deeper when you need it

License

MIT