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

Connect Zephex MCP

Link Cursor, Claude Code, or VS Code to Zephex so the AI in that app can use tools. This is the right page if you want to connect — not the Terminal-only CLI page. Watching videos does not require any download.

Should I download anything? Not to watch videos (0 MB). To connect an editor: paste config from the dashboard (0 MB if you paste config by hand · ~30–85 MB Node only if you run the setup wizard) or run setup once if you want the wizard. You do not need the Terminal CLI page for normal use.

Watch setup video first · Terminal commands (optional)

Connect = link Cursor, Claude Code, or VS Code to Zephex so the AI in that app can use tools (search code, check packages, etc.).
mcpcli / zephex in Terminal = you type commands in Terminal yourself. Different from connect — you do not need this to watch videos.
MCP = the protocol editors use to talk to Zephex. You can ignore this word if you only watch videos or paste a config once.
Zephex is not a big app from a random download site. For connect-in-editor you usually only need a free account + a small config paste, not a huge installer.

Tip: Run setup once per editor, then fully quit the app (Cmd+Q). npx zephex doctor confirms 10 tools before you debug inside the editor UI. The same setup writes ~/.zephex/credentials.json so Mode 2 terminal tools work too.

AFTER CONNECT — TERMINAL WORKS TOO

You do not need a second product for the shell. After setup, cd into a project and run answer-card commands:

npm install -g zephexmcpcli initcd your-appmcpcli overviewmcpcli find-code "auth"mcpcli safe expressmcpcli check-testmcpcli check url https://example.commcpcli doctor

Start here	Purpose
`overview`	Product story + stack bars
`get-context`	Structured project brief
`find-code`	Search symbols / strings
`summarize`	Plain-English file read
`check-test`	Run tests + failures
`safe`	Package safety before install
`architecture`	How modules wire
`check url`	Live URL security audit
`remember`	Save a project fact
`connect`	Wire an editor MCP

More: Terminal Mode 2 · All commands

WATCH FIRST (NO DOWNLOAD)

Setup video

Browser-only walkthrough — 0 MB download.

Homepage demo

See tools in action before installing.

SETUP FLOW

Run setup

npx -y zephex@latest setup --cursor or interactive picker.

Browser OAuth

Config written

HTTP for Cursor/Claude Code; stdio npx bridge for VS Code and most others.

Restart editor

MCP servers load at startup — reload window is often not enough.

Verify

mcpcli doctor + ask agent for tools/list.

MCPCLI — SHORT SETUP COMMAND

Terminal CLI needs Node.js 18+ (or Docker). Check with node -v. No Node? start from zero (MB + steps) · 6 install methods

mcpcli is the short install name for the Zephex MCP CLI (npm package zephex). Same binary, same API key, same 10 tools — you can type mcpcli instead of zephex after a one-time install. Official package name on npm remains zephex; command aliases ship inside that package (v2.4.6+).

Node.js required (or alternatives)

Includes best download path and how many MB each option uses — see download sizes.

mcpcli, npx zephex, and npm install -g zephex are Node.js programs. They need Node.js 18+ and npm on your PATH (or Node inside Docker). Zephex in the browser or in an editor over HTTPS does not replace that for terminal Mode 2.

Quick answer: Most people should install Node.js LTS, restart the terminal, then run npm install -g zephex && mcpcli setup. Pick another row in the table only if Node or global install is not possible on your machine.

BEST DOWNLOAD · HOW MANY MB?

Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org (one installer), then the Zephex CLI from npm. Total download is not huge — on the order of tens of MB for Node, plus about 2.4 MB for the CLI itself.

# Best download for most people (small + permanent):# 1) Node.js LTS installer — ~30 MB (Windows) or ~85 MB (macOS) one-time download#    https://nodejs.org/en/download# 2) Then in terminal (Zephex CLI is only ~2–3 MB from npm):npm install -g zephexmcpcli setup # Smallest try-before-install (still needs Node for npx):npx zephex setup# First run downloads zephex (~2–3 MB) to npm cache; no huge SDK.

What you download	Approx. download	After install on disk
Node.js LTS (Windows .msi) — best base for most users	~30 MB	~100–250 MB
Node.js LTS (macOS .pkg)	~84 MB	~100–250 MB
zephex CLI only (`npm install -g zephex`)	~2.4 MB	~3–20 MB in npm cache
npx zephex setup (no global install)	Same ~2.4 MB CLI on first run	Cached under `~/.npm`; no separate “Zephex app” installer
Docker `node:22-alpine` (no local Node)	~45–60 MB image pull	Docker Desktop ~500+; image ~45–60 MB
Editor-only MCP (HTTPS + API key)	0 MB CLI — config only	No Node required on laptop

Sizes vary slightly by Node version and OS. You are not downloading a large IDE or a multi-GB SDK — just Node (if needed) and a small npm package. Tools run against https://zephex.dev/mcp; your project code is not uploaded as a full repo by default.

Step 1 — check what you already have:

node -vnpm -vwhich nodewhich npm

v18.x, v20.x, or v22.x → you are ready; skip to after Node is installed.
command not found → Node is missing; install below or use Docker / editor-only.
v16 or lower → upgrade Node; the CLI requires 18+.

Step 2 — pick the best path for you:

Your situation	Best option	Notes
New user, can install software	Node.js LTS + `npm install -g zephex && mcpcli setup`	Recommended. Shortest commands: mcpcli, zepx, zephex.
Have Node, try before installing globally	`npx zephex setup`	~5s first download; nothing permanent except credentials.
Use Bun instead of Node day-to-day	`bun install -g zephex`	Still a JS runtime; see Bun block below.
Use pnpm	`pnpm add -g zephex`	Same CLI; see pnpm block below.
No Node on host; Docker allowed	Docker + npx in container	Mount `$HOME` so credentials survive.
No Node, no Docker; only Cursor / Claude	Editor MCP (HTTP)	Mode 1 in editor — not the same as terminal mcpcli tools.
Corporate laptop, no installs	Manual JSON config	Paste MCP config + API key; setup wizard optional on another machine.
Only need terminal tools occasionally	`npx zephex …` per command	Needs Node each time; no global PATH entry.

INSTALL NODE.JS (MAC · WINDOWS · LINUX)

Download the LTS installer if you are unsure — it includes npm. After install, close and reopen your terminal (required on Windows so PATH updates).

# macOS — recommended for most users# Option A: Homebrew (developers)brew install node # Option B: Official LTS installer (everyone)# Download from https://nodejs.org/en/download# Run the .pkg, then restart Terminal # Option C: Version manager (multiple Node versions)# fnm: https://github.com/Schniz/fnm# nvm: https://github.com/nvm-sh/nvm

# Windows — recommended for most users# Option A: winget (Windows 10/11)winget install OpenJS.NodeJS.LTS # Option B: Official LTS installer# https://nodejs.org/en/download — check "Add to PATH" during install# Then open a NEW Command Prompt or PowerShell window # Verify (new window):node -vnpm -v

# Linux — pick one# Option A: NodeSource (Debian/Ubuntu)curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs # Option B: Distro packages (may be older — need v18+)# sudo apt install nodejs npm   # only if version >= 18 # Option C: nvm (no sudo, per-user)# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash# nvm install --lts# nvm use --lts

Step 3 — after Node works, run Zephex setup:

npm install -g zephex && mcpcli setup

Without global install (still needs Node + npm for npx):

npx zephex setupnpx -p zephex mcpcli setup

BUN & PNPM (ALTERNATIVE RUNTIMES)

These still require a JavaScript runtime on the machine — not a substitute for “no Node at all.”

bun install -g zephexmcpcli setup# or one-shot:bunx zephex setup

pnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setup

No Node on this computer? Use Docker (Node runs inside the image) or editor-only MCP. Docker still requires Docker Desktop / Engine on the host.

# Docker Desktop or Engine required on the hostdocker pull node:22-alpine # Setup (writes ~/.zephex + editor configs on YOUR machine)docker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup # Terminal tool in your repo (mount project folder)cd /path/to/your-appdocker run -it --rm \  -v "$HOME:/root" \  -v "$(pwd):/work" \  -w /work \  node:22-alpine \  npx -y zephex get-context

Optional alias so daily commands look like local mcpcli:

# ~/.bashrc or ~/.zshrc — shorter daily commandsalias mcpcli='docker run -it --rm -v "$HOME:/root" -w "$(pwd):/work" -w /work node:22-alpine npx -y zephex' mcpcli setupmcpcli get-context

Full CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.

EDITOR ONLY — NO LOCAL NODE

If you only want MCP tools inside Cursor or Claude Code and never run commands in Terminal, you can connect over HTTPS without installing Node on your laptop. Terminal Mode 2 (mcpcli get-context, etc.) still needs Node or Docker somewhere.

# No local Node needed for Cursor / Claude Code (hosted HTTP)# 1. Create a key: https://zephex.dev/dashboard/api-keys# 2. In Cursor: Settings → MCP → add server URL:#    https://zephex.dev/mcp#    Header: Authorization: Bearer YOUR_API_KEY# Or run setup on ANY machine that has Node once, copy the key into the editor. # Full wizard (needs Node somewhere once):# mcpcli setup --cursor

TROUBLESHOOTING

# "command not found: node" or "command not found: npx"# → Node is not installed OR not on your PATH.# Fix: install LTS from nodejs.org, restart terminal, run node -v again. # "mcpcli: command not found" after npm install -g# → Global npm bin not on PATH, or install did not finish.# Fix: npm install -g zephex#       npm bin -g    # add this folder to PATH# Or skip global: npx zephex setup # EACCEs / permission denied on npm install -g (macOS/Linux)# Fix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global# Add to ~/.zshrc: export PATH="$HOME/.npm-global/bin:$PATH" # Old Node (v16 or below)# Fix: upgrade to Node 18+ LTS — zephex CLI will not run on EOL Node.

FAQ

Question	Answer
Do I need Node.js to use Zephex at all?	Only for the terminal CLI (mcpcli / npx zephex). Editor MCP via hosted HTTPS (Cursor, Claude Code) can work without Node on your laptop if you paste an API key or HTTP config. Terminal tools always need Node somewhere — your machine or Docker.
What is the best install for a new user?	Install Node.js LTS from nodejs.org (includes npm), restart the terminal, then run: npm install -g zephex && mcpcli setup. That gives the shortest commands forever.
I cannot install software on my work laptop.	Use editor-only MCP (manual JSON or dashboard key) — see Install methods → Manual JSON. Or run setup once on a personal machine, copy the API key, paste into work editor config. Terminal CLI on the work machine may be blocked without Docker approval.
I have Node for another project — is that enough?	Yes, if node -v shows v18 or higher. You do not need a separate Node install for Zephex. Use the same npm/npx.
Does the AI editor install Node for me?	Sometimes. Cursor/VS Code may bundle npx for MCP stdio configs, but that does not put mcpcli on your system PATH for Mode 2 terminal use. For terminal tools, install Node yourself or use Docker.
Docker still needs something installed?	Docker Desktop (or docker CLI) on the host — not Node. The container image includes Node and runs npx zephex for you.
How many MB will this download?	Node.js LTS installer is roughly 30 MB (Windows) or 85 MB (macOS) — not hundreds of MB. The zephex CLI package from npm is about 2–3 MB. npx zephex setup only adds that CLI download on first run (cached after). Docker pulls a ~50 MB Node Alpine image plus the same small zephex package inside the container.
What is the best way to download if I have nothing installed?	Use the official Node.js LTS installer from nodejs.org (includes npm), restart your terminal, then run npm install -g zephex && mcpcli setup. That is the smallest hassle long-term. If you truly cannot install Node, use editor-only MCP (no download) or Docker if your IT allows it.

More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex

First time (any OS, Node already installed)

Pick one path — both work the first time you run setup:

Recommended — global install (shortest commands forever):

npm install -g zephex && mcpcli setup

One-shot without global install (pick one):

npx zephex setupnpx -p zephex mcpcli setup

Plain mcpcli setup only works after npm install -g zephex (or the combined line above). That is expected — there is no separate npm package named mcpcli on the public registry.

After install — daily commands

mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctor

All of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.

Terminal-only vs editor MCP

MCP CLI (Mode 2) runs in your shell — no AI agent required. mcpcli setup when you pick Terminal / CLI only does not change Cursor/VS Code MCP config. Use mcpcli setup --cursor (or another flag) if you also want tools inside the editor.

logout vs disconnect: mcpcli logout removes only ~/.zephex terminal credentials — your editor can keep using MCP. mcpcli disconnect removes Zephex from an editor config and revokes the key — not the same as logout. You can use terminal tools and editor MCP together with one API key; you do not run two separate products.

Who can run it?

Anyone in the world can download and run mcpcli / zephex from npm (public CLI). Your hosted MCP tools at https://zephex.dev/mcp require your API key from setup — strangers cannot use your quota without a key. Keys stay in ~/.zephex (or editor config); nothing secret is baked into the npm package.

Connect MCP (editors) · Terminal tools · Full command list · Install & package names · Install methods (no Node / Docker / manual) · CLI in Docker

CLI — RUN THESE FIRST

From any folder (Node 18+). The wizard opens your browser, creates a CLI-scoped key, writes the editor MCP config, and verifies tools.

# Recommended — global install, then short commands (Mac / Windows / Linux)npm install -g zephex && mcpcli setup # Same setup with flagsmcpcli setup --cursormcpcli setup --vscodemcpcli setup --claude-codemcpcli setup --windsurf --project # One-shot without global installnpx -p zephex mcpcli setup # Official npm name still worksnpx -y zephex setup # After setup: restart the editor (or Reload Window)mcpcli doctormcpcli statusmcpcli list

login is an alias for setup: npx zephex login --cursor = same as setup.

WHAT SETUP DOES

Detects or accepts your editor flag (see table below).

Opens browser OAuth at zephex.dev (unless you pass --api-key).

Creates an API key scoped for CLI + MCP.

Writes the config file — hosted HTTP for Cursor and Claude Code; stdio npx -y zephex for most others.

Saves the same key to ~/.zephex/credentials.json for terminal tools.

Calls the MCP endpoint and confirms 10 tools are available.

How setup signs you in (one browser visit)

Stdio editors never re-auth per tool call — the API key is written once into config env. HTTP editors (Cursor) store Bearer in headers.

You must restart the editor (or use Reload Window) after setup. MCP servers load at startup. Browser sign-in is one-time per setup — stdio editors reuse the key from config env; HTTP editors store Bearer in headers.

HTTP VS STDIO — DECISION TREE

Setup picks transport per editor automatically. Use this tree if you are configuring manually or debugging a broken install. Full guide: HTTP vs stdio.

→ Hosted HTTP

When: Cursor, Claude Code, or Crush (setup writes HTTP). Editor talks directly to https://zephex.dev/mcp with Bearer token — no local npx process.

Best for: Editors with native remote MCP support; package-only tools (check_package, audit_headers) without local file reads.

→ stdio (npx bridge)

When: VS Code, OpenCode, Windsurf, Zed, Continue, Kilo, and 15+ others. Editor spawns npx -y zephex as a child process.

Best for: Repo-aware tools (get_project_context, find_code, check_test) that read your workspace files locally.

Transport policy — stdio vs HTTP + repair

npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.

Common mistake: Registering both HTTP and stdio zephex in one config, or using legacy HTTP where stdio is expected. Run npx -y zephex@latest repair — it migrates VS Code, Zed, Continue, and others to stdio without touching Cursor/Claude Code HTTP.

SETUP WRITES HTTP

cursor, claude-code, crush

SETUP WRITES STDIO

VS Code, OpenCode, Codex, Gemini, Windsurf, Kiro, Zed, Factory, Copilot CLI, and more

EDITOR FLAGS

Skip the interactive picker with one flag. Pair --project for repo-local config (e.g. .cursor/mcp.json).

Editor	Command
Cursor	`npx zephex setup --cursor`
Claude Code	`npx zephex setup --claude`
Claude Desktop	`npx zephex setup --claude-desktop`
VS Code	`npx zephex setup --vscode`
OpenCode	`npx zephex setup --opencode`
Codex CLI	`npx zephex setup --codex`
Gemini CLI	`npx zephex setup --gemini`
Antigravity	`npx zephex setup --antigravity`
TRAE	`npx zephex setup --trae`
Windsurf	`npx zephex setup --windsurf`
Zed	`npx zephex setup --zed`
Warp	`npx zephex setup --warp`
Kiro IDE / Kiro CLI	`npx zephex setup --kiro`
JetBrains AI Assistant	`npx zephex setup --jetbrains`
Factory Droid	`npx zephex setup --droid`
Cline	`npx zephex setup --cline`
Kilo Code	`npx zephex setup --kilo`
Crush	`npx zephex setup --crush`
Hermes	`npx zephex setup --hermes`
ChatGPT	`npx zephex setup --chatgpt`
Continue	`npx zephex setup --continue`
GitHub Copilot CLI	`npx zephex setup --copilot`
Roo Code	`npx zephex setup --roo`
Amp	`npx zephex setup --amp`

Where setup writes config (all platforms)

Same npx zephex setup command — paths differ by OS. Windows uses %USERPROFILE% and %APPDATA%.

Full list: Supported editors · per-editor guides under Editors. Run mcpcli list to see which config files exist on this machine.

TERMINAL FIRST (NO EDITOR)

You can use Zephex from the shell before connecting any editor. Setup still saves ~/.zephex/credentials.json so Mode 2 works immediately.

Terminal Mode 2 — How a Command Runs

No AI agent in the loop. Your shell runs npx zephex; the CLI uploads a search index from disk (inline_files) and calls the same hosted endpoint as your editor.

# Copy-paste test flow (no AI agent) — mcpcli = zephexnpm install -g zephexmcpcli initmcpcli doctorcd your-app   # folder with package.json + srcmcpcli overviewmcpcli get-contextmcpcli find-code "test"mcpcli safe lodashmcpcli check-testmcpcli check url https://example.commcpcli remember "first run used overview + get-context"mcpcli logoutmcpcli setup   # sign in againmcpcli update --check

Complete Mode 2 guide: CLI without an AI agent (10 hosted tools in terminal).

FIVE-MINUTE TEST

Five-Minute Test (No Editor Required)

Prove Mode 2 works from your shell before you connect Cursor or VS Code.

MODE 1 (EDITOR) VS MODE 2 (TERMINAL)

Mode	Who runs tools	How you start
Mode 1 — Editor MCP	Your AI agent in Cursor, Claude, VS Code, …	`npx zephex setup --cursor` (or any editor flag)
Mode 2 — Terminal CLI	You in bash/zsh/PowerShell — human-readable output	Same setup saves credentials; then `npx zephex get-context`

Both modes use the same API key and https://zephex.dev/mcp. Terminal guide: Terminal CLI · CLI without an AI agent.

VERIFY THE CONNECTION

# In Cursor / Claude / VS Code chat, ask the agent:"What MCP tools do you have?"# You should see 10 Zephex tools (get_project_context, read_code, find_code, …)

From terminal: npx zephex doctor checks Node, network, and MCP; npx zephex status shows key + tier; npx zephex list shows which editor configs exist on disk.

MANUAL CONFIG (NO WIZARD)

Create a key at zephex.dev/dashboard/keys, then paste into your editor file.

CURSOR / CLAUDE CODE (HTTP)

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

VS CODE, WINDSURF, … (STDIO)

{  "mcpServers": {    "zephex": {      "command": "npx",      "args": ["-y", "zephex"],      "env": { "ZEPHEX_API_KEY": "mcp_prod_your_key_here" }    }  }}

HTTP vs stdio details: HTTP vs stdio.

DISCONNECT OR RECONNECT

# Remove Zephex from one editor + revoke key server-sidenpx zephex disconnect --cursornpx zephex disconnect --all # Fresh sign-in and config rewritenpx zephex reconnect --vscode # Terminal-only sign-out (editor configs unchanged)npx zephex logout

Full account reference: CLI account & auth.

COMMON ISSUES

Tools not showing

Restart editor after setup. Run npx zephex doctor.

401 / unauthorized

Key revoked or wrong env. Run npx zephex reconnect --cursor.

Wrong project context

Open the repo root in the editor, or cd into the app folder in terminal.

More: MCP troubleshooting · npx zephex · Setup walkthrough.

Installation

Connect Zephex MCP

Watch setup video first · Terminal commands (optional)

Connect = link Cursor, Claude Code, or VS Code to Zephex so the AI in that app can use tools (search code, check packages, etc.).
mcpcli / zephex in Terminal = you type commands in Terminal yourself. Different from connect — you do not need this to watch videos.
MCP = the protocol editors use to talk to Zephex. You can ignore this word if you only watch videos or paste a config once.
Zephex is not a big app from a random download site. For connect-in-editor you usually only need a free account + a small config paste, not a huge installer.

AFTER CONNECT — TERMINAL WORKS TOO

You do not need a second product for the shell. After setup, cd into a project and run answer-card commands:

npm install -g zephexmcpcli initcd your-appmcpcli overviewmcpcli find-code "auth"mcpcli safe expressmcpcli check-testmcpcli check url https://example.commcpcli doctor

Start here	Purpose
`overview`	Product story + stack bars
`get-context`	Structured project brief
`find-code`	Search symbols / strings
`summarize`	Plain-English file read
`check-test`	Run tests + failures
`safe`	Package safety before install
`architecture`	How modules wire
`check url`	Live URL security audit
`remember`	Save a project fact
`connect`	Wire an editor MCP

More: Terminal Mode 2 · All commands

WATCH FIRST (NO DOWNLOAD)

Setup video

Browser-only walkthrough — 0 MB download.

Homepage demo

See tools in action before installing.

SETUP FLOW

Run setup

npx -y zephex@latest setup --cursor or interactive picker.

Browser OAuth

Config written

HTTP for Cursor/Claude Code; stdio npx bridge for VS Code and most others.

Restart editor

MCP servers load at startup — reload window is often not enough.

Verify

mcpcli doctor + ask agent for tools/list.

MCPCLI — SHORT SETUP COMMAND

Terminal CLI needs Node.js 18+ (or Docker). Check with node -v. No Node? start from zero (MB + steps) · 6 install methods

Node.js required (or alternatives)

Includes best download path and how many MB each option uses — see download sizes.

BEST DOWNLOAD · HOW MANY MB?

# Best download for most people (small + permanent):# 1) Node.js LTS installer — ~30 MB (Windows) or ~85 MB (macOS) one-time download#    https://nodejs.org/en/download# 2) Then in terminal (Zephex CLI is only ~2–3 MB from npm):npm install -g zephexmcpcli setup # Smallest try-before-install (still needs Node for npx):npx zephex setup# First run downloads zephex (~2–3 MB) to npm cache; no huge SDK.

What you download	Approx. download	After install on disk
Node.js LTS (Windows .msi) — best base for most users	~30 MB	~100–250 MB
Node.js LTS (macOS .pkg)	~84 MB	~100–250 MB
zephex CLI only (`npm install -g zephex`)	~2.4 MB	~3–20 MB in npm cache
npx zephex setup (no global install)	Same ~2.4 MB CLI on first run	Cached under `~/.npm`; no separate “Zephex app” installer
Docker `node:22-alpine` (no local Node)	~45–60 MB image pull	Docker Desktop ~500+; image ~45–60 MB
Editor-only MCP (HTTPS + API key)	0 MB CLI — config only	No Node required on laptop

Step 1 — check what you already have:

node -vnpm -vwhich nodewhich npm

v18.x, v20.x, or v22.x → you are ready; skip to after Node is installed.
command not found → Node is missing; install below or use Docker / editor-only.
v16 or lower → upgrade Node; the CLI requires 18+.

Step 2 — pick the best path for you:

Your situation	Best option	Notes
New user, can install software	Node.js LTS + `npm install -g zephex && mcpcli setup`	Recommended. Shortest commands: mcpcli, zepx, zephex.
Have Node, try before installing globally	`npx zephex setup`	~5s first download; nothing permanent except credentials.
Use Bun instead of Node day-to-day	`bun install -g zephex`	Still a JS runtime; see Bun block below.
Use pnpm	`pnpm add -g zephex`	Same CLI; see pnpm block below.
No Node on host; Docker allowed	Docker + npx in container	Mount `$HOME` so credentials survive.
No Node, no Docker; only Cursor / Claude	Editor MCP (HTTP)	Mode 1 in editor — not the same as terminal mcpcli tools.
Corporate laptop, no installs	Manual JSON config	Paste MCP config + API key; setup wizard optional on another machine.
Only need terminal tools occasionally	`npx zephex …` per command	Needs Node each time; no global PATH entry.

INSTALL NODE.JS (MAC · WINDOWS · LINUX)

Download the LTS installer if you are unsure — it includes npm. After install, close and reopen your terminal (required on Windows so PATH updates).

# macOS — recommended for most users# Option A: Homebrew (developers)brew install node # Option B: Official LTS installer (everyone)# Download from https://nodejs.org/en/download# Run the .pkg, then restart Terminal # Option C: Version manager (multiple Node versions)# fnm: https://github.com/Schniz/fnm# nvm: https://github.com/nvm-sh/nvm

# Windows — recommended for most users# Option A: winget (Windows 10/11)winget install OpenJS.NodeJS.LTS # Option B: Official LTS installer# https://nodejs.org/en/download — check "Add to PATH" during install# Then open a NEW Command Prompt or PowerShell window # Verify (new window):node -vnpm -v

# Linux — pick one# Option A: NodeSource (Debian/Ubuntu)curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs # Option B: Distro packages (may be older — need v18+)# sudo apt install nodejs npm   # only if version >= 18 # Option C: nvm (no sudo, per-user)# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash# nvm install --lts# nvm use --lts

Step 3 — after Node works, run Zephex setup:

npm install -g zephex && mcpcli setup

Without global install (still needs Node + npm for npx):

npx zephex setupnpx -p zephex mcpcli setup

BUN & PNPM (ALTERNATIVE RUNTIMES)

These still require a JavaScript runtime on the machine — not a substitute for “no Node at all.”

bun install -g zephexmcpcli setup# or one-shot:bunx zephex setup

pnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setup

No Node on this computer? Use Docker (Node runs inside the image) or editor-only MCP. Docker still requires Docker Desktop / Engine on the host.

# Docker Desktop or Engine required on the hostdocker pull node:22-alpine # Setup (writes ~/.zephex + editor configs on YOUR machine)docker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup # Terminal tool in your repo (mount project folder)cd /path/to/your-appdocker run -it --rm \  -v "$HOME:/root" \  -v "$(pwd):/work" \  -w /work \  node:22-alpine \  npx -y zephex get-context

Optional alias so daily commands look like local mcpcli:

# ~/.bashrc or ~/.zshrc — shorter daily commandsalias mcpcli='docker run -it --rm -v "$HOME:/root" -w "$(pwd):/work" -w /work node:22-alpine npx -y zephex' mcpcli setupmcpcli get-context

Full CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.

EDITOR ONLY — NO LOCAL NODE

# No local Node needed for Cursor / Claude Code (hosted HTTP)# 1. Create a key: https://zephex.dev/dashboard/api-keys# 2. In Cursor: Settings → MCP → add server URL:#    https://zephex.dev/mcp#    Header: Authorization: Bearer YOUR_API_KEY# Or run setup on ANY machine that has Node once, copy the key into the editor. # Full wizard (needs Node somewhere once):# mcpcli setup --cursor

TROUBLESHOOTING

# "command not found: node" or "command not found: npx"# → Node is not installed OR not on your PATH.# Fix: install LTS from nodejs.org, restart terminal, run node -v again. # "mcpcli: command not found" after npm install -g# → Global npm bin not on PATH, or install did not finish.# Fix: npm install -g zephex#       npm bin -g    # add this folder to PATH# Or skip global: npx zephex setup # EACCEs / permission denied on npm install -g (macOS/Linux)# Fix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global# Add to ~/.zshrc: export PATH="$HOME/.npm-global/bin:$PATH" # Old Node (v16 or below)# Fix: upgrade to Node 18+ LTS — zephex CLI will not run on EOL Node.

FAQ

Question	Answer
Do I need Node.js to use Zephex at all?	Only for the terminal CLI (mcpcli / npx zephex). Editor MCP via hosted HTTPS (Cursor, Claude Code) can work without Node on your laptop if you paste an API key or HTTP config. Terminal tools always need Node somewhere — your machine or Docker.
What is the best install for a new user?	Install Node.js LTS from nodejs.org (includes npm), restart the terminal, then run: npm install -g zephex && mcpcli setup. That gives the shortest commands forever.
I cannot install software on my work laptop.	Use editor-only MCP (manual JSON or dashboard key) — see Install methods → Manual JSON. Or run setup once on a personal machine, copy the API key, paste into work editor config. Terminal CLI on the work machine may be blocked without Docker approval.
I have Node for another project — is that enough?	Yes, if node -v shows v18 or higher. You do not need a separate Node install for Zephex. Use the same npm/npx.
Does the AI editor install Node for me?	Sometimes. Cursor/VS Code may bundle npx for MCP stdio configs, but that does not put mcpcli on your system PATH for Mode 2 terminal use. For terminal tools, install Node yourself or use Docker.
Docker still needs something installed?	Docker Desktop (or docker CLI) on the host — not Node. The container image includes Node and runs npx zephex for you.
How many MB will this download?	Node.js LTS installer is roughly 30 MB (Windows) or 85 MB (macOS) — not hundreds of MB. The zephex CLI package from npm is about 2–3 MB. npx zephex setup only adds that CLI download on first run (cached after). Docker pulls a ~50 MB Node Alpine image plus the same small zephex package inside the container.
What is the best way to download if I have nothing installed?	Use the official Node.js LTS installer from nodejs.org (includes npm), restart your terminal, then run npm install -g zephex && mcpcli setup. That is the smallest hassle long-term. If you truly cannot install Node, use editor-only MCP (no download) or Docker if your IT allows it.

More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex

First time (any OS, Node already installed)

Pick one path — both work the first time you run setup:

Recommended — global install (shortest commands forever):

npm install -g zephex && mcpcli setup

One-shot without global install (pick one):

npx zephex setupnpx -p zephex mcpcli setup

Plain mcpcli setup only works after npm install -g zephex (or the combined line above). That is expected — there is no separate npm package named mcpcli on the public registry.

After install — daily commands

mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctor

All of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.

Terminal-only vs editor MCP

Who can run it?

Connect MCP (editors) · Terminal tools · Full command list · Install & package names · Install methods (no Node / Docker / manual) · CLI in Docker

CLI — RUN THESE FIRST

From any folder (Node 18+). The wizard opens your browser, creates a CLI-scoped key, writes the editor MCP config, and verifies tools.

# Recommended — global install, then short commands (Mac / Windows / Linux)npm install -g zephex && mcpcli setup # Same setup with flagsmcpcli setup --cursormcpcli setup --vscodemcpcli setup --claude-codemcpcli setup --windsurf --project # One-shot without global installnpx -p zephex mcpcli setup # Official npm name still worksnpx -y zephex setup # After setup: restart the editor (or Reload Window)mcpcli doctormcpcli statusmcpcli list

login is an alias for setup: npx zephex login --cursor = same as setup.

WHAT SETUP DOES

Detects or accepts your editor flag (see table below).

Opens browser OAuth at zephex.dev (unless you pass --api-key).

Creates an API key scoped for CLI + MCP.

Writes the config file — hosted HTTP for Cursor and Claude Code; stdio npx -y zephex for most others.

Saves the same key to ~/.zephex/credentials.json for terminal tools.

Calls the MCP endpoint and confirms 10 tools are available.

How setup signs you in (one browser visit)

Stdio editors never re-auth per tool call — the API key is written once into config env. HTTP editors (Cursor) store Bearer in headers.

HTTP VS STDIO — DECISION TREE

Setup picks transport per editor automatically. Use this tree if you are configuring manually or debugging a broken install. Full guide: HTTP vs stdio.

→ Hosted HTTP

When: Cursor, Claude Code, or Crush (setup writes HTTP). Editor talks directly to https://zephex.dev/mcp with Bearer token — no local npx process.

Best for: Editors with native remote MCP support; package-only tools (check_package, audit_headers) without local file reads.

→ stdio (npx bridge)

When: VS Code, OpenCode, Windsurf, Zed, Continue, Kilo, and 15+ others. Editor spawns npx -y zephex as a child process.

Best for: Repo-aware tools (get_project_context, find_code, check_test) that read your workspace files locally.

Transport policy — stdio vs HTTP + repair

npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.

SETUP WRITES HTTP

cursor, claude-code, crush

SETUP WRITES STDIO

VS Code, OpenCode, Codex, Gemini, Windsurf, Kiro, Zed, Factory, Copilot CLI, and more

EDITOR FLAGS

Skip the interactive picker with one flag. Pair --project for repo-local config (e.g. .cursor/mcp.json).

Editor	Command
Cursor	`npx zephex setup --cursor`
Claude Code	`npx zephex setup --claude`
Claude Desktop	`npx zephex setup --claude-desktop`
VS Code	`npx zephex setup --vscode`
OpenCode	`npx zephex setup --opencode`
Codex CLI	`npx zephex setup --codex`
Gemini CLI	`npx zephex setup --gemini`
Antigravity	`npx zephex setup --antigravity`
TRAE	`npx zephex setup --trae`
Windsurf	`npx zephex setup --windsurf`
Zed	`npx zephex setup --zed`
Warp	`npx zephex setup --warp`
Kiro IDE / Kiro CLI	`npx zephex setup --kiro`
JetBrains AI Assistant	`npx zephex setup --jetbrains`
Factory Droid	`npx zephex setup --droid`
Cline	`npx zephex setup --cline`
Kilo Code	`npx zephex setup --kilo`
Crush	`npx zephex setup --crush`
Hermes	`npx zephex setup --hermes`
ChatGPT	`npx zephex setup --chatgpt`
Continue	`npx zephex setup --continue`
GitHub Copilot CLI	`npx zephex setup --copilot`
Roo Code	`npx zephex setup --roo`
Amp	`npx zephex setup --amp`

Where setup writes config (all platforms)

Same npx zephex setup command — paths differ by OS. Windows uses %USERPROFILE% and %APPDATA%.

Full list: Supported editors · per-editor guides under Editors. Run mcpcli list to see which config files exist on this machine.

TERMINAL FIRST (NO EDITOR)

You can use Zephex from the shell before connecting any editor. Setup still saves ~/.zephex/credentials.json so Mode 2 works immediately.

Terminal Mode 2 — How a Command Runs

No AI agent in the loop. Your shell runs npx zephex; the CLI uploads a search index from disk (inline_files) and calls the same hosted endpoint as your editor.

# Copy-paste test flow (no AI agent) — mcpcli = zephexnpm install -g zephexmcpcli initmcpcli doctorcd your-app   # folder with package.json + srcmcpcli overviewmcpcli get-contextmcpcli find-code "test"mcpcli safe lodashmcpcli check-testmcpcli check url https://example.commcpcli remember "first run used overview + get-context"mcpcli logoutmcpcli setup   # sign in againmcpcli update --check

Complete Mode 2 guide: CLI without an AI agent (10 hosted tools in terminal).

FIVE-MINUTE TEST

Five-Minute Test (No Editor Required)

Prove Mode 2 works from your shell before you connect Cursor or VS Code.

MODE 1 (EDITOR) VS MODE 2 (TERMINAL)

Mode	Who runs tools	How you start
Mode 1 — Editor MCP	Your AI agent in Cursor, Claude, VS Code, …	`npx zephex setup --cursor` (or any editor flag)
Mode 2 — Terminal CLI	You in bash/zsh/PowerShell — human-readable output	Same setup saves credentials; then `npx zephex get-context`

Both modes use the same API key and https://zephex.dev/mcp. Terminal guide: Terminal CLI · CLI without an AI agent.

VERIFY THE CONNECTION

# In Cursor / Claude / VS Code chat, ask the agent:"What MCP tools do you have?"# You should see 10 Zephex tools (get_project_context, read_code, find_code, …)

From terminal: npx zephex doctor checks Node, network, and MCP; npx zephex status shows key + tier; npx zephex list shows which editor configs exist on disk.

MANUAL CONFIG (NO WIZARD)

Create a key at zephex.dev/dashboard/keys, then paste into your editor file.

CURSOR / CLAUDE CODE (HTTP)

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

VS CODE, WINDSURF, … (STDIO)

{  "mcpServers": {    "zephex": {      "command": "npx",      "args": ["-y", "zephex"],      "env": { "ZEPHEX_API_KEY": "mcp_prod_your_key_here" }    }  }}

HTTP vs stdio details: HTTP vs stdio.

DISCONNECT OR RECONNECT

# Remove Zephex from one editor + revoke key server-sidenpx zephex disconnect --cursornpx zephex disconnect --all # Fresh sign-in and config rewritenpx zephex reconnect --vscode # Terminal-only sign-out (editor configs unchanged)npx zephex logout

Full account reference: CLI account & auth.

COMMON ISSUES

Tools not showing

Restart editor after setup. Run npx zephex doctor.

401 / unauthorized

Key revoked or wrong env. Run npx zephex reconnect --cursor.

Wrong project context

Open the repo root in the editor, or cd into the app folder in terminal.

More: MCP troubleshooting · npx zephex · Setup walkthrough.

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Connect Zephex MCP

Run setup

Browser OAuth

Config written

Restart editor

Verify

Node.js required (or alternatives)

First time (any OS, Node already installed)

After install — daily commands

Terminal-only vs editor MCP

Who can run it?

More

→ Hosted HTTP

→ stdio (npx bridge)

Tools not showing

401 / unauthorized

Wrong project context

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Connect Zephex MCP

Run setup

Browser OAuth

Config written

Restart editor

Verify

Node.js required (or alternatives)

First time (any OS, Node already installed)

After install — daily commands

Terminal-only vs editor MCP

Who can run it?

More

→ Hosted HTTP

→ stdio (npx bridge)

Tools not showing

401 / unauthorized

Wrong project context