<div align="center">

<img src="assets/hero.svg" alt="UniGrok · Grok MCP Server & Gateway — one Grok server, every IDE, zero pasted API keys" width="100%"/>

Quick Start · IDE Setup · Tool Surface · Architecture · Security

</div>

UniGrok · Grok MCP Server & Gateway

What is UniGrok? One local Grok server that every coding agent on your machine shares — self-routing across xAI's API and the Grok CLI subscription, with per-call cost tracking, while your API key never leaves the server.

UniGrok is a local-first Grok MCP server and gateway for xAI's Grok models. It runs once on your machine, keeps the xAI credential on the server side, and lets Cursor, Claude Desktop, Claude Code, VS Code, Codex, Antigravity, and other MCP clients share the same Grok agent over Streamable HTTP — with dual-plane routing across the xAI API and the Grok CLI subscription, per-call cost tracking, and a browser Control Center.

Current development release: v0.5.3.

Use it as:

• A shared multi-IDE Grok MCP server at http://localhost:4765/mcp (4765 spells GROK on a phone keypad).
• An OpenAI-compatible local gateway for unigrok-agent.
• A structured agent harness with web search, X search, code execution, files, image/video generation, session memory, telemetry, and reflection.

Quick Start

git clone https://github.com/djtelicloud/grok-mcp-server.git
cd grok-mcp-server
uv run python main.py init

The init command:

• copies example.env to .env when .env does not already exist;
• leaves an existing .env untouched;
• prints copy-paste configs for VS Code, Claude Desktop, Claude Code, and Codex;
• points every IDE at the shared HTTP endpoint instead of asking each IDE for the raw xAI key.

Edit .env and set your key — grab one from the xAI Console if you don't have one yet:

XAI_API_KEY=your_real_xai_api_key

Then start the shared service:

docker compose up --build -d
curl -s http://localhost:4765/healthz

Authenticate the independent CLI subscription plane once per machine:

docker compose run --rm grok-cli-auth

The helper uses xAI's device-code login and stores the refreshable OAuth state in the dedicated unigrok-cli-auth Docker volume. It is service identity, not project identity: never repeat this when switching repositories. Ordinary startup is noninteractive and remains API-capable when CLI auth is absent.

This is a standalone, workspace-neutral service. The image runs its baked application from /app, keeps mutable data in a Docker volume at /state, and does not mount this repository or whichever project an IDE currently has open. Register the endpoint globally once, then switch projects freely; those projects need no .agents, .codex, .grok, or other UniGrok files.

When Grok needs project material, the calling IDE should send deliberately selected excerpts, diffs, errors, or other context in agent.workspace_context. UniGrok never guesses that MCP registration grants filesystem access.

Open the local Control Center:

http://localhost:4765/ui/

Install Script

For a guided local bootstrap:

./install.sh

It checks for uv, git, and Docker, syncs the Python environment, runs init, and validates Docker Compose when Docker is available.

IDE Setup

The default architecture is one shared Docker service:

http://localhost:4765/mcp

Each IDE should send a stable X-Client-ID header so telemetry, sessions, and budgets stay separated by caller.

Cursor

With Cursor joining the xAI family (SpaceX's June 2026 agreement to acquire Anysphere), it's the natural first-class Grok IDE — add UniGrok in 10 seconds. Create or edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally) and paste:

{
  "mcpServers": {
    "unigrok": {
      "url": "http://localhost:4765/mcp",
      "name": "UniGrok MCP Gateway",
      "description": "Shared Grok agent with live Control Center, cost tracking, reasoning guard, OKF + WebMCP self-discovery",
      "headers": { "X-Client-ID": "cursor" }
    }
  }
}

VS Code

{
  "servers": {
    "unigrok": {
      "type": "http",
      "url": "http://localhost:4765/mcp",
      "headers": { "X-Client-ID": "vscode" }
    }
  }
}

Claude Desktop

Claude Desktop config-file servers are stdio commands, so bridge to HTTP with mcp-remote:

{
  "mcpServers": {
    "unigrok": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:4765/mcp",
        "--header", "X-Client-ID: claude-desktop"
      ]
    }
  }
}

Claude Code

claude mcp add --transport http unigrok http://localhost:4765/mcp \
  --header "X-Client-ID: claude-code"

Codex

[mcp_servers.grok]
url = "http://localhost:4765/mcp"
http_headers = { "X-Client-ID" = "codex" }

If UNIGROK_API_KEYS is set in .env, also add Authorization: Bearer <token> to each client config.

More detail, including Antigravity/Gemini notes, lives in docs/ide-setup.md.

Run Modes

Stdio MCP:

uv run python main.py

HTTP gateway:

uv run python main.py --http

Packaged console script:

uv run unigrok-mcp init
uv run unigrok-mcp --http

Supervised helper:

./grok-mcp-helper.sh init
./grok-mcp-helper.sh start
./grok-mcp-helper.sh status

Tool Surface

Start with agent. It is the headline tool and should handle most nontrivial requests.

Core tools:

• agent: auto-routed Grok agent with modes auto, fast, reasoning, thinking, and research.
• grok_reflect: focused structured critique for plans, code-review notes, outputs, and architecture decisions.
• chat: plain Grok chat with optional model pinning and session history.
• chat_with_vision: image analysis.
• chat_with_files: grounded answers over uploaded xAI files.
• submit_research_job, get_research_job, list_research_jobs: deferred xAI research jobs.
• remember_fact, search_knowledge, forget_fact, distill_session: local knowledge memory.
• recall_workspace_memory, record_landed_outcome, explain_workspace_evidence, workspace_memory_status: explicit, contributor-only, commit-anchored engineering evidence for agents developing UniGrok itself. Records require a verified scripts/land receipt; automatic prompt injection is off. These tools are not on the public HTTP service.
• web_search, x_search, remote_code_execution: xAI server-side tools.
• read_local_file, list_project_files: workspace inspection.
• git_status, git_diff, git_log, git_show: read-only Git context.
• generate_image, generate_video, extend_video: Grok Imagine media.

Explainable model selection

agent(model=None, mode="auto") uses one deterministic, local-first selector:

• capability classes are planning, coding, vision, and research;
• planning cold-starts on grok-4.5, coding on grok-build-0.1, and research on the live Grok 4.20 multi-agent slug;
• explicit model pins and UNIGROK_*_MODEL overrides always win;
• the live catalog is cached for 15 minutes and a discovery failure uses the bundled model directory instead of blocking a request;
• fresh eval calibration is considered before local telemetry, but a peer needs mature evidence and a 15-point success-rate advantage to replace the stable default.

Every AgentResult includes a routing receipt, and new telemetry rows retain that same prompt-free receipt. It explains the task feature bucket, route class, candidate models, evidence source, selected model, pin source, and any failover. The Control Center renders these receipts directly rather than guessing a reason from aggregate metrics.

The public Streamable HTTP MCP endpoint intentionally exposes the unified agent surface for IDE use. The full stdio server exposes the broader tool set for local trusted workflows.

Workspace-memory operations are also available locally as unigrok-mcp memory status, unigrok-mcp memory sync, and unigrok-mcp memory import. The Git Notes ref is local provenance and is not part of ordinary branch pushes.

The public HTTP surface stays intentionally small: agent, status, discovery, and the disabled-by-default maintenance helper. In unrelated projects, call agent normally and add workspace_context only when local project evidence is needed.

Architecture

UniGrok has three boundaries:

• Transport: stdio MCP, Streamable HTTP MCP, and an OpenAI-compatible /v1 facade all route into the same agent harness.
• Model plane: authenticated local Grok CLI is preferred for compatible, unpinned work; API-backed Grok models serve explicit pins and API-native thinking, vision, and multi-agent research capabilities.
• Local state: SQLite stores sessions, telemetry, research jobs, task memory, distilled knowledge, and commit-anchored workspace evidence under the configured state directory.

flowchart LR
    CU[Cursor] --> GW
    CC[Claude Code] --> GW
    VS[VS Code] --> GW
    CX[Codex] --> GW
    AG[Antigravity] --> GW
    GW["UniGrok gateway<br/>localhost:4765 (GROK)<br/>/mcp · /v1 · /ui"]
    GW -->|API plane · XAI_API_KEY| API["xAI API<br/>grok-4.5 · grok-build-0.1"]
    GW -->|CLI plane · OAuth subscription| CLI["Grok CLI live catalog<br/>grok-4.5 · composer"]
    GW --- ST[("SQLite<br/>sessions · cost · jobs")]

Full design detail lives in architecture.md.

UniGrok strips XAI_API_KEY from every CLI subprocess. This prevents a CLI invocation from silently charging the API credential and makes the reported CLI/API routing split a real credential and allowance boundary.

The Control Center usage ledger keeps those planes honest: xAI API requests store the exact per-response billed cost; CLI subscription requests store local counts, latency, success, model, and estimated tokens without inventing a per-request dollar cost. xAI does not expose SuperGrok subscription quota, so UniGrok never invents remaining allowance or merges API billing into CLI statistics. An optional advanced organization-billing comparison exists, but ordinary users do not need a team id or management key for local telemetry.

Credential-plane onboarding

grok_mcp_discover_self, grok_mcp_status, /runtimez, and every public agent result expose the same non-secret credential_planes contract. A fresh IDE agent should inspect its notices once per state:

• If CLI is missing or unauthenticated, continue on API when possible and ask permission before rebuilding/installing the CLI or starting device auth.
• If XAI_API_KEY is missing but CLI is ready, prompt once without blocking compatible CLI work; an API-only capability blocks until the key is securely configured.
• If both planes are unavailable, stop model work and present both repair actions. Never request the API key in chat or write it into the caller's project; it belongs only in the global UniGrok service environment.

The local default is UNIGROK_PLANE_POLICY=cli_first. Explicit model pins and UNIGROK_*_MODEL overrides still win. Set the policy to api_first only when API-native behavior is intentionally preferred over subscription utilization. CLI-first model slugs come from the authenticated live grok models catalog, not a hard-coded subscription catalog; coding currently prefers composer while reasoning uses the live CLI default.

Useful endpoints in HTTP mode:

• GET /healthz
• GET /readyz
• GET /metrics
• GET /metrics?format=prometheus
• GET /v1/models
• POST /v1/chat/completions
• POST /mcp

WebMCP & OKF Discovery

UniGrok combines Google's Open Knowledge Format (OKF) with the experimental WebMCP API currently published as a W3C Web Machine Learning Community Group draft. WebMCP is not yet a W3C Standard.

1. OKF Knowledge Bundle

The directory /docs/okf/ contains a fully self-describing documentation bundle for agents:

• okf-manifest.json: Lists index and topic documents.
• index.md: Main entrypoint for agent reading.
• Topic-specific files (e.g. agent-tool.md, reasoning-guard.md) detail tool schemas, inputs/outputs, model pinning, and telemetry budget controls.

2. WebMCP-Enabled Docs & Console

When running the HTTP gateway, visiting http://localhost:4765/ui/ exposes browser-native WebMCP tools under document.modelContext. Any agent visiting this page can automatically discover and call:

• get_schema(tool_name): Returns the Pydantic JSON schema of a given UniGrok tool.
• example_call(mode): Returns JSON templates/examples for different operational modes.
• simulate_reasoning_guard: Simulates checking if a model meets the required reasoning level.
• fetch_okf_bundle: Returns the metadata and file paths in the OKF bundle.

3. Pre-Visit Manifest Discovery

A project-specific experimental manifest is exposed at /.well-known/webmcp so compatible agents and extensions can pre-discover the page's capabilities without performing heavy DOM scrapes:

curl -s http://localhost:4765/.well-known/webmcp

4. Running a WebMCP-Compatible Browser or Bridge

To let an IDE agent call these experimental browser tools, use a browser build or extension that exposes document.modelContext, and keep the target tab at http://localhost:4765/ui/ open.

Security Model

• XAI_API_KEY belongs in the UniGrok server/container environment, not in each IDE client.
• example.env is a template only. The runtime loads .env when present and rejects the placeholder key.
• Docker publishes 127.0.0.1:4765 by default.
• Set UNIGROK_API_KEYS before exposing the gateway beyond loopback.
• Git write tools are disabled unless local runtime flags explicitly enable them.
• Container restart is disabled by default and should only be enabled for a trusted local process with Docker access.

See SECURITY.md for vulnerability reporting and deployment guidance.

Development

uv sync
uv run pytest
uv run python -m compileall -q src evals main.py
docker compose config
docker compose -f docker-compose.dev.yml config

Contributors who want live mounted source use the separate service on port 4766:

docker compose -f docker-compose.dev.yml up --build -d

That contributor endpoint conditionally adds the commit-anchored memory tools, so repository-local IDE skills can recall and record verified landing evidence. Those tools never appear on the stable service used by unrelated projects.

scripts/land may reconcile that contributor service after tests pass. It never rebuilds or restarts the stable port-4765 service automatically.

Optional Grok Dial Plan

UniGrok can expose memorable phoneword “speed-dial” ports without creating extra services or databases. Enable the overlay with:

docker compose -f docker-compose.yml -f docker-compose.dials.yml up --build -d

Dial	Phoneword	Default agent mode
2886	AUTO	auto
3278	FAST	fast
7327	REAS	reasoning
8465	THNK	thinking
7724	RSCH	research

Every dial reaches the same stable process, sessions, authentication, and Control Center. The original Host port supplies a default only when the MCP caller omits mode; an explicit tool argument always wins. Normal users should register 4765 once. The dial overlay is an optional power-user interface.

Run the full local test suite before publishing changes. Offline evals can be run with:

uv run python -m evals run --check-baseline

See CONTRIBUTING.md for contribution workflow and PR expectations.

---

Built by @DavidLJohnston · Built for Grok · Powered by xAI · Follow @xai on X