codex-xai-oauth

Codex plugin that exposes xAI/Grok tools through a local stdio MCP server. It is based on the reusable OAuth and xAI client behavior from ../opencode-xai-oauth, adapted for Codex plugin packaging instead of OpenCode provider hooks.

What Works

• xai_status
• xai_login_instructions
• xai_generate_text
• xai_web_search
• xai_x_search
• xai_image_generate
• xai_tts
• xai_video_generate

xai_image_generate calls xAI /images/generations. Default model is grok-imagine-image, default response format is url, and resolution supports 1k or 2k. Pass artifact_dir to save returned URL or b64_json images locally and include artifact metadata in the tool result.

Unofficial / Use At Your Own Risk

This project is not affiliated with or endorsed by xAI. OAuth behavior and media endpoints can change. You are responsible for reviewing and complying with xAI terms, API policies, X policies, account rules, and quota or billing implications before using it.

Development

npm install
npm test
npm run typecheck
npm run build
python3 /Users/ilseoblee/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

Release notes are tracked in RELEASE_NOTES.md.

Install / Doctor

From a checkout:

npm run setup
npm run doctor

Via npx:

npx codex-xai-oauth setup
npx codex-xai-oauth doctor

Globally from GitHub:

npm install -g github:islee23520/codex-xai-oauth
codex-xai-oauth setup
codex-xai-oauth doctor

setup syncs this package into the local linalab Codex marketplace and installs codex-xai-oauth@linalab. doctor checks the build output, Codex plugin install, MCP registration, and credential status.

Authentication

The default OAuth store is the shared xAI OIDC file at ~/.grok/auth.json. This project reads and writes that shared store by default; it does not require a specific Grok CLI build. CODEX_XAI_OAUTH_AUTH_FILE is available only when you intentionally want a separate package-specific auth file.

Browser OAuth login:

npx codex-xai-oauth login

OAuth device flow for headless environments:

npx codex-xai-oauth login --device

API-key fallback:

export XAI_API_KEY=xai-...

Status:

npx codex-xai-oauth status

Generate an image directly from the NPX CLI:

npx codex-xai-oauth image --prompt "minimal blue dot icon" --resolution 2k

Save generated image payloads to local artifacts:

npx codex-xai-oauth image --prompt "minimal blue dot icon" --response-format b64_json --artifact-dir .codex-xai-artifacts

OAuth credentials are stored by default as an xAI OIDC entry in:

~/.grok/auth.json

Legacy package-specific OAuth credentials are still read as a fallback from:

~/.config/codex-xai-oauth/auth.json

Credential precedence:

• CODEX_XAI_OAUTH_AUTH_FILE, when explicitly set.
• ~/.grok/auth.json.
• ~/.config/codex-xai-oauth/auth.json legacy fallback.
• XAI_API_KEY.
• Codex model provider experimental_bearer_token.

Overrides:

• CODEX_XAI_OAUTH_AUTH_FILE: custom package-format OAuth auth JSON path.
• CODEX_XAI_OAUTH_GROK_AUTH_FILE: custom shared xAI OIDC auth JSON path, mainly for tests or nonstandard installs.
• XAI_API_KEY: API-key fallback.
• XAI_BASE_URL: custom xAI-compatible base URL.

OpenAI-Compatible Proxy

After OAuth login, start a local /v1 proxy backed by the stored xAI OAuth token:

npx codex-xai-oauth serve-openai --host 127.0.0.1 --port 8787

Print a CLIProxyAPIPlus openai-compatibility snippet:

npx codex-xai-oauth cliproxy-config

The proxy exposes:

• /v1/models
• /v1/chat/completions
• /v1/responses
• /v1/images/generations

/v1/images/generations and /images/generations forward prompt, model, n, size, resolution, and response_format. Invalid n, resolution, or response_format values return a 400 response before any upstream xAI call.

Codex Plugin Surface

• .codex-plugin/plugin.json declares the plugin metadata, skill bundle, and MCP config.
• .mcp.json starts the stdio MCP server from dist/mcp/server.js.
• skills/xai-grok/SKILL.md tells Codex when to use the tools and how to avoid leaking secrets.

Built-In Skills

The plugin bundles a general skill plus one dedicated skill for each MCP tool listed in What Works:

• xai-grok: umbrella skill for plugin overview, setup orientation, or multi-tool requests when no dedicated xai_* skill is a better fit.
• xai_status: dedicated trigger for xai_status.
• xai_login_instructions: dedicated trigger for xai_login_instructions.
• xai_generate_text: dedicated trigger for xai_generate_text.
• xai_web_search: dedicated trigger for xai_web_search.
• xai_x_search: dedicated trigger for xai_x_search.
• xai_image_generate: dedicated trigger for xai_image_generate.
• xai_tts: dedicated trigger for xai_tts.
• xai_video_generate: dedicated trigger for xai_video_generate.

The dedicated xai_image_generate skill lets Codex route natural-language image requests to xai_image_generate.

MCP tool arguments:

{
  "prompt": "tiny minimalist blue dot icon on white background",
  "resolution": "2k",
  "artifact_dir": ".codex-xai-artifacts"
}

Equivalent CLI:

npx codex-xai-oauth image \
  --prompt "tiny minimalist blue dot icon on white background" \
  --resolution 2k \
  --artifact-dir .codex-xai-artifacts

For base64 image payloads saved locally:

npx codex-xai-oauth image \
  --prompt "a cinematic robot reading a book" \
  --response-format b64_json \
  --artifact-dir .codex-xai-artifacts

Build before installing or using the MCP server:

npm run build