Installation
The zephex npm package ships the setup wizard from mcp-proxy/src/commands/setup.ts. It signs you in, creates a CLI-scoped API key, writes your editor's MCP config, and verifies 10 tools — stdio bridge for most editors, hosted HTTP for Cursor and Claude Code.
Tip: Pin @latest on every setup and repair run. Stale npm cache is the #1 cause of missing tools after an upgrade.
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+).
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.
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 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 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. |
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 18+ LTS — zephex CLI will not run on EOL Node.| 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
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
These six commands cover 90% of daily use — setup, diagnose, fix, inventory, and the two most-used terminal tools.
SETUP
setup · login, connect, sign-inFirst connect — browser OAuth, writes editor MCP config + ~/.zephex/credentials.json
npx -y zephex@latest setup --cursorDOCTOR
doctorHealth check — Node version, network, MCP reachability, stdio pins, API key
npx -y zephex@latest doctorREPAIR
repairFix unpinned zephex, wrong OpenCode shape, legacy HTTP→stdio for filesystem editors
npx -y zephex@latest repairLIST
list · lsShow every supported editor — installed configs highlighted
npx -y zephex@latest listGET-CONTEXT
get-context · context, stack, framework, .Mode 2 — compact project brief from cwd (uploads local index)
mcpcli get-contextFIND-CODE
find-code · find, search, grep, usagesMode 2 — ripgrep-style repo search with AST-aware results
mcpcli find-code "auth middleware"The setup command auto-detects your editor (or use a flag below), runs OAuth in the browser unless you pass --api-key, writes the config file, and verifies the connection.
npm install -g zephex && mcpcli setup # Or one-shot (no global install)npx -p zephex mcpcli setup # Official package name — always @latest until npm cache is freshnpx -y zephex@latest setupAlready have a key? Skip the browser step — paste a real key from the dashboard:
npx -y zephex setup --cursor --api-key mcp_prod_your-key-herenpx -y zephex setup --opencode --api-key mcp_prod_your-key-herenpx -y zephex setup --vscode --api-key mcp_prod_your-key-hereFull cheat sheet: all editors + flags.
? Which editor? (interactive picker) → Cursor (writes hosted HTTP url) → VS Code (writes stdio: npx -y zephex) → Claude Code (claude mcp add --transport http, or HTTP JSON) → OpenCode, Codex, Gemini, Windsurf, Kiro, Zed, … (stdio for local file tools) ✓ API key created via browser sign-in✓ Config written to the correct path for that editor✓ Connection verified — 10 tools available✓ Restart the editor (or reload window) to activateStdio editors never re-auth per tool call — the API key is written once into config env. HTTP editors (Cursor) store Bearer in headers.
Global by default — setup writes user-level config so Zephex works in every project. It also removes stale project-level Zephex entries that shadow global config. Add --project only when you intentionally want workspace-scoped config.
Runs Node version check, pings https://zephex.dev/mcp, validates API key, and confirms stdio config pins zephex@latest.
npx -y zephex@latest doctorFixes unpinned stdio, OpenCode command-array shape, PATH hints for GUI-launched editors, and migrates legacy HTTP blocks to stdio for filesystem editors. Does not change Cursor/Claude Code HTTP.
npx -y zephex@latest repairShows all 22+ supported editors with install status — which config files exist on disk and their transport type.
npx -y zephex@latest listCommon mistake: Re-running setup repeatedly mints new API keys (free tier: 3 max). Run repair first, then doctor — only re-run setup if you need a fresh key or new editor.
After setup saves ~/.zephex/credentials.json, run hosted tools in any terminal — no editor required.
Compact project brief — stack, auth, key files, env vars. Uploads a local file index from cwd by default.
cd your-appmcpcli get-contextmcpcli get-context databasemcpcli get-context github:vercel/next.jsFast repo-wide search — ripgrep-backed with symbol-aware results. Use --cwd for monorepos.
mcpcli find-code "auth middleware"mcpcli find-code "validateToken" --cwd apps/webmcpcli usages AuthServiceFull terminal guide: Terminal CLI · CLI without an AI agent.
# 1. Always @latest (not cached older npm)npx -y zephex@latest setup --cursor # 2. Verify immediatelynpx -y zephex@latest doctornpx -y zephex@latest list # 3. Fix stdio pins / OpenCode shapenpx -y zephex@latest repair # 4. Fully quit editor (Cmd+Q), reopen, new sessionDetails: MCP troubleshooting.
| Command | When to use |
|---|---|
npx -y zephex@latest setup | Connect editor(s) — global config, browser OAuth, writes correct stdio/HTTP |
npx -y zephex@latest init | First-run wizard (terminal + editor picker) |
npx -y zephex@latest list | Which editors have Zephex config on this machine |
npx -y zephex@latest doctor | Node, network, stdio pins, config health |
npx -y zephex@latest repair | Fix unpinned zephex, wrong OpenCode command array, legacy entries |
npx -y zephex@latest usage | Monthly quota vs plan limit |
npx -y zephex@latest disconnect --cursor | Remove editor config + revoke key |
npx -y zephex@latest update --apply | Upgrade global npm install |
Zephex does not ship curl -fsSL … | bash. Setup is editor JSON + optional browser login — not a system service. npx -y zephex@latest setup is the one-liner equivalent. See install methods.
Same npx zephex setup command — paths differ by OS. Windows uses %USERPROFILE% and %APPDATA%.
Credentials land in ~/.zephex/credentials.json. Run npx -y zephex@latest list after setup to confirm paths.
npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.
After upgrading the CLI, run repair before re-running setup. Account lifecycle: CLI account · HTTP vs stdio.
Tool commands send the full API key; the proxy resolves user_id and logs usage_events. mcpcli usage only sends a 20-char prefix — tier counts, not identity.
Mode 2 terminal tools send the full Bearer key; the proxy resolves your account and logs usage. npx zephex usage is a lightweight quota check.
When your editor uses stdio, it launches npx -y zephex as a child process. The CLI forwards JSON-RPC to https://zephex.dev/mcp and reads local files for repo-aware tools.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Test your API key before configuring an editor:
# Run as stdio MCP server (what most editors call after setup)ZEPHEX_API_KEY="mcp_sk_your_key" npx -y zephexCursor
Claude Code
Claude Desktop
VS Code
OpenCode
Codex CLI
Gemini CLI
Antigravity
TRAE
Windsurf
Zed
Warp
Kiro IDE / Kiro CLI
JetBrains AI Assistant
Factory Droid
Cline
Kilo Code
Crush
Hermes
ChatGPT
Continue
GitHub Copilot CLI
Roo Code
Amp
Write project-scoped config (pair with any editor flag)
Also: --api-key mcp_sk_… (skip OAuth), --mcp / --cli (skills mode). See supported editors.
NODE
Node.js 18 or later (for npx)
NETWORK
HTTPS to zephex.dev on port 443
ACCOUNT
Setup creates the key, or use an existing key from the dashboard