Core documentation content is fully readable without JavaScript. The table of contents, assistant, and some copy buttons enhance the experience but are not required.

Installation

Install Methods — Pick the one that fits your environment

Six ways to get Zephex running. From the easiest (npx, no install) to the most flexible (manual JSON config, no Node.js needed).

Decision flowchart

              Do you have Node.js 20+ installed?
                            │
              ┌─────────────┴─────────────┐
            YES                           NO
              │                            │
              ▼                            ▼
        Want zero install?          Want a container?
              │                            │
        ┌─────┴─────┐                ┌─────┴─────┐
       YES         NO              YES           NO
        │           │                │            │
        ▼           ▼                ▼            ▼
   Method 1    Method 2-4       Method 5     Method 6
   npx        npm/bun/pnpm     Docker       Manual JSON
   zephex     install -g       container    (no install)

Method 0 — curl installer (terminal CLI only)

One line for Mode 2 terminal tools (same as the web terminal — type / for commands). Installs Node if missing, then zephex + browser sign-in. Does not wire Cursor or Claude.

curl -fsSL https://zephex.dev/install.sh | bash # Then in your project:cd your-appzephex              # interactive shell — /overview, /context, /find …mcpcli get-context # Editor MCP (separate):npx zephex setup --cursor

Pros: Works on a fresh Mac with no Node. Grok-style one command.

Cons: First run downloads Node (~85MB once) + zephex (~7MB). Editor setup is a different command.

Method 1 — npx (no global install)

One command. Downloads zephex from npm to a temp folder and runs it. Nothing stays on your system.

# Recommended — always latest, skip npx cache and confirm promptnpx -y zephex@latest setup # Connect one editor (global config — works in every project)npx -y zephex@latest setup --cursornpx -y zephex@latest setup --antigravitynpx -y zephex@latest setup --opencode # After setup — verify and fix stdio pinsnpx -y zephex@latest doctornpx -y zephex@latest listnpx -y zephex@latest repair

Pros: No install. Pin @latest to avoid stale cache. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). Type npx each time unless you install globally.

Global by default: setup writes user-level config (~/.cursor/mcp.json, ~/.config/opencode/opencode.json, etc.) and removes conflicting project-level Zephex entries. Add --project only when you want workspace-scoped config.

Method 2 — npm global install

Standard global install. Adds zephex to your PATH so you can type zephex without npx.

# Install oncenpm install -g zephex # Then run anywherezephex setupzephex listzephex tools # Update laternpm install -g zephex@latest

Pros: Type zephex instead of npx zephex. Faster startup (no download).

Cons: One install per Node version. May need sudo on some systems.

Method 3 — Bun

If you use Bun as your runtime, install zephex globally with Bun's package manager.

# Installbun install -g zephex # Runzephex setup # Or run via bunx (no install)bunx zephex setup

Pros: Bun is faster than Node for installs. Same binary as the npm version.

Cons: Requires Bun runtime installed.

Method 4 — pnpm

For pnpm users.

# Install globallypnpm add -g zephex # Runzephex setup # Or via pnpx (no install)pnpm dlx zephex setup

Method 5 — Docker

For users without Node.js, or those who want everything sandboxed. Run Zephex in a container without touching your host system.

Quick start with Docker

# Pull the latest imagedocker pull node:22-alpine # Run zephex setup inside a container, mounting your home dirdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup

This mounts your home directory into the container so the wizard can write the editor config files (~/.cursor/mcp.json, ~/.claude.json, etc.) to your real machine.

Run a specific command

# List installed editorsdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex list # Run doctordocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex doctor

Make it easier with a shell alias

# Add to ~/.bashrc or ~/.zshrcalias zephex='docker run -it --rm -v "$HOME:/root" -w /root node:22-alpine npx -y zephex' # Then use like normalzephex setupzephex listzephex doctor

Build your own image

If you don't want to download the package every time, build a thin image with Zephex pre-installed:

FROM node:22-alpineRUN npm install -g zephexENTRYPOINT ["zephex"]

# Build it oncedocker build -t zephex-cli . # Run any commanddocker run -it --rm -v "$HOME:/root" -w /root zephex-cli setupdocker run -it --rm -v "$HOME:/root" -w /root zephex-cli list

Pros: No Node.js required on the host. Everything sandboxed. Cleanup is just deleting the container/image.

Cons: Slower startup (container boot). Need Docker installed. Volume mounts get tricky on Windows.

Method 6 — Manual JSON config (no Node.js, no Docker)

If you can't (or don't want to) install Node.js or Docker, you can write the editor config file by hand. The Zephex CLI is just a convenience — the actual MCP connection is HTTP-based.

Step 1: Get an API key

Sign in at zephex.dev/dashboard/keys with GitHub or Google. Click "Create Key", copy the value (starts with mcp_prod_).

Step 2: Find your editor's MCP config file

Editor             Config file path
──────────────────────────────────────────────────────────────────────────
Cursor             ~/.cursor/mcp.json
Claude Code        ~/.claude.json
VS Code            <project>/.vscode/mcp.json
Codex              ~/.codex/config.toml
OpenCode           ~/.config/opencode/opencode.json
Windsurf           ~/.codeium/windsurf/mcp_config.json
Zed                ~/.config/zed/settings.json
Warp               ~/.agents/.mcp.json
Gemini CLI         ~/.gemini/settings.json
Kiro               ~/.kiro/settings/mcp.json
Cline (VS Code)    Library/Application Support/Code/User/globalStorage/
                     saoudrizwan.claude-dev/settings/cline_mcp_settings.json
JetBrains          <project>/.junie/mcp/mcp.json
Kilo Code          Library/Application Support/Code/User/globalStorage/
                     kilocode.kilo-code/settings/mcp_settings.json
Amp                ~/.config/amp/settings.json
Continue           ~/.continue/config.yaml
GitHub Copilot CLI ~/.copilot/mcp-config.json
Factory Droid      ~/.factory/mcp.json
Claude Desktop     Library/Application Support/Claude/claude_desktop_config.json
Antigravity        ~/.gemini/antigravity/mcp_config.json
TRAE               <project>/.trae/mcp.json

Step 3: Add the Zephex entry

For most editors (Cursor, Claude Code, Windsurf, Zed, Kiro, Cline, Kilo, Copilot, Droid, Claude Desktop, Antigravity, TRAE):

{  "mcpServers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For VS Code (note servers not mcpServers):

{  "servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Zed (note context_servers):

{  "context_servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Antigravity (note serverUrl not url):

{  "mcpServers": {    "zephex": {      "serverUrl": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Codex (TOML format, not JSON):

[mcp_servers.zephex]url = "https://zephex.dev/mcp" [mcp_servers.zephex.http_headers]Authorization = "Bearer YOUR_API_KEY_HERE"

Step 4: Restart your editor

Quit completely and reopen. The Zephex tools will appear in your editor's tool list.

Pros: No Node.js, no Docker, nothing installed. Works in airgapped or restricted environments.

Cons: You manage the file by hand. To update keys, you edit the file. You don't get the wizard's nice 3-step picker.

Comparison table

Method        Speed     Disk    Node?    Docker?    Best for
──────────────────────────────────────────────────────────────────────────────
npx           ●●○       ~0      Yes      No         Trying it once
npm -g        ●●●       ~5MB    Yes      No         Daily use, fast startup
bun -g        ●●●       ~5MB    Bun      No         Bun runtime users
pnpm -g       ●●●       ~5MB    Yes      No         pnpm workspace users
Docker        ●○○       ~120MB  No       Yes        No Node, sandboxed
Manual JSON   ●●●       ~0      No       No         No Node, no Docker, airgapped

Updating Zephex

If installed via npx

Always use @latest to bypass the npx cache:

npx zephex@latest setup

If installed via npm/bun/pnpm

# npmnpm install -g zephex@latest # bunbun install -g zephex@latest # pnpmpnpm add -g zephex@latest

If installed via Docker

# Pull a fresh node image (zephex is downloaded fresh each time with -y)docker pull node:22-alpine # Or rebuild your custom image if you made onedocker build -t zephex-cli --no-cache .

If installed via manual JSON

Nothing to update — you're calling the live https://zephex.dev/mcp endpoint directly. Just keep the API key valid and it works forever.

Uninstall

Remove just the Zephex config from your editors

# Remove from one editornpx zephex disconnect --cursor # Remove from every editornpx zephex disconnect --all # Full cleanup (config + skill + rule files)npx zephex reset --all

Uninstall the CLI itself

# npmnpm uninstall -g zephex # bunbun uninstall -g zephex # pnpmpnpm remove -g zephex # Docker — delete the imagedocker rmi zephex-cli

Common pitfalls (read before re-running setup)

Stale npm cache: use npx -y zephex@latest, not plain npx zephex.
Re-running setup too often: each OAuth run can mint a new API key — free tier allows 3 keys.
Editor not restarted: fully quit (Cmd+Q on Mac), not just close the window.
Works in terminal, fails in editor: GUI apps lack nvm/Homebrew on PATH — run npx -y zephex@latest repair.
Works in one repo, not another: project-level .vscode/mcp.json, opencode.json, or .mcp.json shadowing global — run global setup again or check npx -y zephex@latest list.
Antigravity: global path only (~/.gemini/antigravity/mcp_config.json); quit app fully and start a new agent session.

Full decision tree: MCP troubleshooting.

Where to next

Setup Walkthrough — visual guide to the wizard flow
CLI Commands Reference — every command explained
Supported Editors — config path for each editor
Plans — Free / Pro / Max tier comparison

Installation

Install Methods — Pick the one that fits your environment

Six ways to get Zephex running. From the easiest (npx, no install) to the most flexible (manual JSON config, no Node.js needed).

Decision flowchart

              Do you have Node.js 20+ installed?
                            │
              ┌─────────────┴─────────────┐
            YES                           NO
              │                            │
              ▼                            ▼
        Want zero install?          Want a container?
              │                            │
        ┌─────┴─────┐                ┌─────┴─────┐
       YES         NO              YES           NO
        │           │                │            │
        ▼           ▼                ▼            ▼
   Method 1    Method 2-4       Method 5     Method 6
   npx        npm/bun/pnpm     Docker       Manual JSON
   zephex     install -g       container    (no install)

Method 0 — curl installer (terminal CLI only)

One line for Mode 2 terminal tools (same as the web terminal — type / for commands). Installs Node if missing, then zephex + browser sign-in. Does not wire Cursor or Claude.

curl -fsSL https://zephex.dev/install.sh | bash # Then in your project:cd your-appzephex              # interactive shell — /overview, /context, /find …mcpcli get-context # Editor MCP (separate):npx zephex setup --cursor

Pros: Works on a fresh Mac with no Node. Grok-style one command.

Cons: First run downloads Node (~85MB once) + zephex (~7MB). Editor setup is a different command.

Method 1 — npx (no global install)

One command. Downloads zephex from npm to a temp folder and runs it. Nothing stays on your system.

# Recommended — always latest, skip npx cache and confirm promptnpx -y zephex@latest setup # Connect one editor (global config — works in every project)npx -y zephex@latest setup --cursornpx -y zephex@latest setup --antigravitynpx -y zephex@latest setup --opencode # After setup — verify and fix stdio pinsnpx -y zephex@latest doctornpx -y zephex@latest listnpx -y zephex@latest repair

Pros: No install. Pin @latest to avoid stale cache. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). Type npx each time unless you install globally.

Method 2 — npm global install

Standard global install. Adds zephex to your PATH so you can type zephex without npx.

# Install oncenpm install -g zephex # Then run anywherezephex setupzephex listzephex tools # Update laternpm install -g zephex@latest

Pros: Type zephex instead of npx zephex. Faster startup (no download).

Cons: One install per Node version. May need sudo on some systems.

Method 3 — Bun

If you use Bun as your runtime, install zephex globally with Bun's package manager.

# Installbun install -g zephex # Runzephex setup # Or run via bunx (no install)bunx zephex setup

Pros: Bun is faster than Node for installs. Same binary as the npm version.

Cons: Requires Bun runtime installed.

Method 4 — pnpm

For pnpm users.

# Install globallypnpm add -g zephex # Runzephex setup # Or via pnpx (no install)pnpm dlx zephex setup

Method 5 — Docker

For users without Node.js, or those who want everything sandboxed. Run Zephex in a container without touching your host system.

Quick start with Docker

# Pull the latest imagedocker pull node:22-alpine # Run zephex setup inside a container, mounting your home dirdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup

This mounts your home directory into the container so the wizard can write the editor config files (~/.cursor/mcp.json, ~/.claude.json, etc.) to your real machine.

Run a specific command

# List installed editorsdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex list # Run doctordocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex doctor

Make it easier with a shell alias

# Add to ~/.bashrc or ~/.zshrcalias zephex='docker run -it --rm -v "$HOME:/root" -w /root node:22-alpine npx -y zephex' # Then use like normalzephex setupzephex listzephex doctor

Build your own image

If you don't want to download the package every time, build a thin image with Zephex pre-installed:

FROM node:22-alpineRUN npm install -g zephexENTRYPOINT ["zephex"]

# Build it oncedocker build -t zephex-cli . # Run any commanddocker run -it --rm -v "$HOME:/root" -w /root zephex-cli setupdocker run -it --rm -v "$HOME:/root" -w /root zephex-cli list

Pros: No Node.js required on the host. Everything sandboxed. Cleanup is just deleting the container/image.

Cons: Slower startup (container boot). Need Docker installed. Volume mounts get tricky on Windows.

Method 6 — Manual JSON config (no Node.js, no Docker)

If you can't (or don't want to) install Node.js or Docker, you can write the editor config file by hand. The Zephex CLI is just a convenience — the actual MCP connection is HTTP-based.

Step 1: Get an API key

Sign in at zephex.dev/dashboard/keys with GitHub or Google. Click "Create Key", copy the value (starts with mcp_prod_).

Step 2: Find your editor's MCP config file

Editor             Config file path
──────────────────────────────────────────────────────────────────────────
Cursor             ~/.cursor/mcp.json
Claude Code        ~/.claude.json
VS Code            <project>/.vscode/mcp.json
Codex              ~/.codex/config.toml
OpenCode           ~/.config/opencode/opencode.json
Windsurf           ~/.codeium/windsurf/mcp_config.json
Zed                ~/.config/zed/settings.json
Warp               ~/.agents/.mcp.json
Gemini CLI         ~/.gemini/settings.json
Kiro               ~/.kiro/settings/mcp.json
Cline (VS Code)    Library/Application Support/Code/User/globalStorage/
                     saoudrizwan.claude-dev/settings/cline_mcp_settings.json
JetBrains          <project>/.junie/mcp/mcp.json
Kilo Code          Library/Application Support/Code/User/globalStorage/
                     kilocode.kilo-code/settings/mcp_settings.json
Amp                ~/.config/amp/settings.json
Continue           ~/.continue/config.yaml
GitHub Copilot CLI ~/.copilot/mcp-config.json
Factory Droid      ~/.factory/mcp.json
Claude Desktop     Library/Application Support/Claude/claude_desktop_config.json
Antigravity        ~/.gemini/antigravity/mcp_config.json
TRAE               <project>/.trae/mcp.json

Step 3: Add the Zephex entry

For most editors (Cursor, Claude Code, Windsurf, Zed, Kiro, Cline, Kilo, Copilot, Droid, Claude Desktop, Antigravity, TRAE):

{  "mcpServers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For VS Code (note servers not mcpServers):

{  "servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Zed (note context_servers):

{  "context_servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Antigravity (note serverUrl not url):

{  "mcpServers": {    "zephex": {      "serverUrl": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Codex (TOML format, not JSON):

[mcp_servers.zephex]url = "https://zephex.dev/mcp" [mcp_servers.zephex.http_headers]Authorization = "Bearer YOUR_API_KEY_HERE"

Step 4: Restart your editor

Quit completely and reopen. The Zephex tools will appear in your editor's tool list.

Pros: No Node.js, no Docker, nothing installed. Works in airgapped or restricted environments.

Cons: You manage the file by hand. To update keys, you edit the file. You don't get the wizard's nice 3-step picker.

Comparison table

Method        Speed     Disk    Node?    Docker?    Best for
──────────────────────────────────────────────────────────────────────────────
npx           ●●○       ~0      Yes      No         Trying it once
npm -g        ●●●       ~5MB    Yes      No         Daily use, fast startup
bun -g        ●●●       ~5MB    Bun      No         Bun runtime users
pnpm -g       ●●●       ~5MB    Yes      No         pnpm workspace users
Docker        ●○○       ~120MB  No       Yes        No Node, sandboxed
Manual JSON   ●●●       ~0      No       No         No Node, no Docker, airgapped

Updating Zephex

If installed via npx

Always use @latest to bypass the npx cache:

npx zephex@latest setup

If installed via npm/bun/pnpm

# npmnpm install -g zephex@latest # bunbun install -g zephex@latest # pnpmpnpm add -g zephex@latest

If installed via Docker

# Pull a fresh node image (zephex is downloaded fresh each time with -y)docker pull node:22-alpine # Or rebuild your custom image if you made onedocker build -t zephex-cli --no-cache .

If installed via manual JSON

Nothing to update — you're calling the live https://zephex.dev/mcp endpoint directly. Just keep the API key valid and it works forever.

Uninstall

Remove just the Zephex config from your editors

# Remove from one editornpx zephex disconnect --cursor # Remove from every editornpx zephex disconnect --all # Full cleanup (config + skill + rule files)npx zephex reset --all

Uninstall the CLI itself

# npmnpm uninstall -g zephex # bunbun uninstall -g zephex # pnpmpnpm remove -g zephex # Docker — delete the imagedocker rmi zephex-cli

Common pitfalls (read before re-running setup)

Stale npm cache: use npx -y zephex@latest, not plain npx zephex.
Re-running setup too often: each OAuth run can mint a new API key — free tier allows 3 keys.
Editor not restarted: fully quit (Cmd+Q on Mac), not just close the window.
Works in terminal, fails in editor: GUI apps lack nvm/Homebrew on PATH — run npx -y zephex@latest repair.
Works in one repo, not another: project-level .vscode/mcp.json, opencode.json, or .mcp.json shadowing global — run global setup again or check npx -y zephex@latest list.
Antigravity: global path only (~/.gemini/antigravity/mcp_config.json); quit app fully and start a new agent session.

Full decision tree: MCP troubleshooting.

Where to next

Setup Walkthrough — visual guide to the wizard flow
CLI Commands Reference — every command explained
Supported Editors — config path for each editor
Plans — Free / Pro / Max tier comparison

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Install Methods — Pick the one that fits your environment

Decision flowchart

Method 0 — curl installer (terminal CLI only)

Method 1 — npx (no global install)

Method 2 — npm global install

Method 3 — Bun

Method 4 — pnpm

Method 5 — Docker

Quick start with Docker

Run a specific command

Make it easier with a shell alias

Build your own image

Method 6 — Manual JSON config (no Node.js, no Docker)

Step 1: Get an API key

Step 2: Find your editor's MCP config file

Step 3: Add the Zephex entry

Step 4: Restart your editor

Comparison table

Updating Zephex

If installed via npx

If installed via npm/bun/pnpm

If installed via Docker

If installed via manual JSON

Uninstall

Remove just the Zephex config from your editors

Uninstall the CLI itself

Common pitfalls (read before re-running setup)

Where to next

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Install Methods — Pick the one that fits your environment

Decision flowchart

Method 0 — curl installer (terminal CLI only)

Method 1 — npx (no global install)

Method 2 — npm global install

Method 3 — Bun

Method 4 — pnpm

Method 5 — Docker

Quick start with Docker

Run a specific command

Make it easier with a shell alias

Build your own image

Method 6 — Manual JSON config (no Node.js, no Docker)

Step 1: Get an API key

Step 2: Find your editor's MCP config file

Step 3: Add the Zephex entry

Step 4: Restart your editor

Comparison table

Updating Zephex

If installed via npx

If installed via npm/bun/pnpm

If installed via Docker

If installed via manual JSON

Uninstall

Remove just the Zephex config from your editors

Uninstall the CLI itself

Common pitfalls (read before re-running setup)

Where to next