Installation
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)
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.
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
npx -y zephex@latest setup --cursor or interactive picker.
Sign in at zephex.dev — CLI receives a scoped API key.
HTTP for Cursor/Claude Code; stdio npx bridge for VS Code and most others.
MCP servers load at startup — reload window is often not enough.
mcpcli doctor + ask agent for tools/list.
No Node? curl -fsSL https://zephex.dev/cli/install.sh | bash. npx/npm need Node.js 22.5+. Check with node -v. Still stuck? start from zero (MB + steps) · 6 install methods
This one-liner is the Mode 2 terminal installer — the same zephex shell you type / in. It is not the editor MCP wizard on the homepage (npx -p zephex mcpcli setup). Same account and API key later; different first command.
curl -fsSL https://zephex.dev/cli/install.sh | bashSame script lives at both URLs (use either):
curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.~/.zephex/node.zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).macOS (Intel or Apple Silicon) — Terminal or iTerm. Needs curl (already there). After install, new Terminal windows pick up PATH from ~/.zshrc and ~/.zprofile. The current window still needs:
source ~/.zephex/env.shLinux (x64 or arm64) — bash, zsh, or fish. Same curl line. PATH is appended to ~/.bashrc / ~/.profile (and fish config if needed). If you installed as one user and launch the desktop as another, the binary will not be on PATH — stay on the same account.
Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:
irm https://zephex.dev/install.ps1 | iexWSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.
~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600)./overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.zephex process does not send your repo to Sentry.source ~/.zephex/env.shcd your-appzephex# type /overview or /helpHosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.
The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:
zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bashCheck what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.
curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.zephex connect --cursor when you want the editor.zephex uninstall # PATH + credentialszephex uninstall --full # delete entire ~/.zephexcommand not found: zephex — source ~/.zephex/env.sh, then open a new tab.source line.zephex.dev— never a random gist.More paths: all install methods · macOS · Linux · Windows · terminal CLI
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+).
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 22+ 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.
Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org or skip Node entirely with the curl installer (~3 MB CLI tarball). npm install -g zephex currently unpacks ~260 MB of unused deps — prefer curl.
# Best download — no Node required (~3 MB CLI; +~50 MB Node only if missing)curl -fsSL https://zephex.dev/cli/install.sh | bash # Already have Node 22.5+ and want editor MCP only:npx -y zephex@latest setup --cursor # Avoid until slim publish: npm install -g zephex / bare npx zephex# Those currently also install unused server libraries (~260 MB).| 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) | ~3 MB | ~260 MB in npm cache |
| npx zephex setup (no global install) | Same ~3 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 npmv18.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 22+.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. |
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 --ltsStep 3 — after Node works, run Zephex setup:
npm install -g zephex && mcpcli setupWithout global install (still needs Node + npm for npx):
npx zephex setupnpx -p zephex mcpcli setupThese 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 setuppnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setupNo 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-contextOptional 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-contextFull CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.
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# "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 22.5+ — or use curl install.sh, which bundles Node.| Question | Answer |
|---|---|
| Do I need Node.js to use Zephex at all? | Not for the curl installer — it bundles Node 22 under ~/.zephex if needed. npx / npm / bun still need Node 22.5+ on PATH. Editor MCP over HTTPS can work with only an API key. |
| What is the best install for a new user? | curl -fsSL https://zephex.dev/cli/install.sh | bash — then source ~/.zephex/env.sh. That works with or without Node. Use npx zephex setup --cursor only when you already have Node 22.5+ and want editor MCP. |
| 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 v22.5 or higher. Below that, use the curl installer — it downloads a private Node 22 instead of failing. |
| 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? | curl installer: ~3 MB CLI tarball, plus ~50 MB Node only if you are below 22.5. npm install -g zephex / npx zephex currently also pull unused server libraries (~260 MB, ~2 minutes) until the slim package is published. Docker is a ~50 MB Node image plus that same npm package. |
| What is the best way to download if I have nothing installed? | curl -fsSL https://zephex.dev/cli/install.sh | bash. If you cannot run curl|bash, use editor-only MCP (paste a key into Cursor) or the web terminal. Do not start with npm install -g until the slim package is on npm. |
More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex
Pick one path — both work the first time you run setup:
Recommended — global install (shortest commands forever):
npm install -g zephex && mcpcli setupOne-shot without global install (pick one):
npx zephex setupnpx -p zephex mcpcli setupPlain 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.
mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctorAll of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.
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.
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
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 listlogin is an alias for setup: npx zephex login --cursor = same as setup.
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.
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.
Setup picks transport per editor automatically. Use this tree if you are configuring manually or debugging a broken install. Full guide: HTTP vs stdio.
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.
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.
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
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 |
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.
You can use Zephex from the shell before connecting any editor. Setup still saves ~/.zephex/credentials.json so Mode 2 works immediately.
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 --checkComplete Mode 2 guide: CLI without an AI agent (10 hosted tools in terminal).
Prove Mode 2 works from your shell before you connect Cursor or VS Code.
| 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.
# 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.
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.
# 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 logoutFull account reference: CLI account & auth.
Restart editor after setup. Run npx zephex doctor.
Key revoked or wrong env. Run npx zephex reconnect --cursor.
Open the repo root in the editor, or cd into the app folder in terminal.
More: MCP troubleshooting · npx zephex · Setup walkthrough.