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 1 — npx (recommended, no install)

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

# Run the wizardnpx zephex setup # Skip the picker — connect Cursor directlynpx zephex setup --cursor # Always use the latest version (skip npx cache)npx zephex@latest setup

Pros: No install. Always uses the latest version. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). You need to type npx every time.

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

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 1 — npx (recommended, no install)

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

# Run the wizardnpx zephex setup # Skip the picker — connect Cursor directlynpx zephex setup --cursor # Always use the latest version (skip npx cache)npx zephex@latest setup

Pros: No install. Always uses the latest version. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). You need to type npx every time.

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

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

Install Methods — Pick the one that fits your environment

Decision flowchart

Method 1 — npx (recommended, no 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

Where to next

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Install Methods — Pick the one that fits your environment

Decision flowchart

Method 1 — npx (recommended, no 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

Where to next