Most Zephex failures are fixable in under two minutes: use zephex@latest, run doctor + list, fully restart the editor, and check for project-level configs shadowing global setup. Start with the avoid-repeat checklist below.
EDITOR INDEX
Each editor has a dedicated setup guide with config path, verify steps, and common issues. Pick yours first — most "0 tools" failures are editor-specific path or transport mistakes.
Cursor, Claude Code, or VS Code shows zero Zephex tools? Walk this tree top to bottom before re-running setup (repeated setup can mint extra API keys on free tier).
Config in the right place? Project vs global matters. Cursor: .cursor/mcp.json in the opened repo root. Claude Code: ~/.claude.json. VS Code: .vscode/mcp.json. Run npx -y zephex@latest list to see every file Zephex knows about on this machine.
JSON valid? Trailing commas and wrong key names break silently. Open the editor guide and copy the block again.
Fully quit the editor? Cmd+Q on Mac — not just close the window. MCP loads at startup for most clients.
Works in terminal but not GUI? GUI apps miss nvm/Homebrew PATH. Run npx -y zephex@latest repair after doctor.
Project shadow? A stale .cursor/mcp.json in one repo overrides global config. Global setup (default, no --project) strips shadows.
Stale npx cache? Always use zephex@latest in args — plain npx zephex can run an old build.
401 Unauthorized? Key in env block for stdio, or Bearer header for HTTP — not only in your shell profile.
Still empty? Open a new agent chat after restart. Some editors cache MCP from the previous session (Antigravity, Warp).
npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.
If doctor flags unpinned stdio or HTTP where stdio is expected, run repair before setup again. Repair migrates filesystem editors to stdio; Cursor, Claude Code, and Crush stay HTTP. See HTTP vs stdio.
AVOID-REPEAT CHECKLIST
Run this sequence after every setup. It catches stale npm cache, unpinned stdio, wrong config paths, and project shadows — the issues that come back on every install.
shell
# Run this after every setup — catches 90% of repeat failuresnpx -y zephex@latest doctornpx -y zephex@latest listnpx -y zephex@latest repair # fix pins + auto HTTP → stdio for local file tools
Global setup is the default — writes user-level config for all editors and removes conflicting project-level Zephex entries. Use --project only when you intentionally want workspace-scoped config.
CLI COMMANDS THAT FIX CONNECTIONS
shell
# Status across all editors on this machinenpx -y zephex@latest list# Health: Node, network, stdio pins, config pathsnpx -y zephex@latest doctor# Fix broken stdio (unpinned zephex, wrong OpenCode shape)npx -y zephex@latest repair# Re-run setup with latest CLI (global by default)npx -y zephex@latest setup --cursornpx -y zephex@latest setup --antigravitynpx -y zephex@latest setup --opencode# Remove stale project-level configs that shadow globalnpx -y zephex@latest setup --cursor # global setup also strips project shadows
Each card lists fixes in order — work through the checklist top to bottom. Critical blocks all tool calls; Common is usually config or PATH.
Works in terminal but editor says npx not found or 0 tools
Common
1
GUI apps (Cursor, VS Code, Antigravity) do not load your shell profile — nvm, Homebrew, and fnm paths are missing.
2
Setup writes PATH hints into the stdio env block; run npx -y zephex@latest repair if doctor flags unpinned stdio.
3
Confirm npx works in a plain terminal: which npx && npx --version.
4
On macOS with nvm: install Node via the official pkg or brew so /usr/local/bin or /opt/homebrew/bin is on the GUI PATH.
5
Fully quit the editor (Cmd+Q on Mac) — not just close the window.
Windows / WSL — paths differ between terminal and editor
Common
1
Native Windows editors (Cursor, VS Code) read %USERPROFILE%\.cursor\mcp.json or .vscode\mcp.json — WSL paths like /mnt/c/... are invisible to the Windows GUI.
2
Pick one environment: either run setup from Windows PowerShell (npx -y zephex@latest setup --cursor) or open the repo inside WSL and use Linux paths (~/.cursor/mcp.json).
3
Credentials live at %USERPROFILE%\.zephex\credentials.json on Windows and ~/.zephex/credentials.json in WSL — they are separate files.
4
For Docker + WSL2: keep repos inside the WSL filesystem (/home/...) for volume mounts; see /docs/platforms/windows.
5
After path fixes, run doctor + list from the same shell you used for setup, then fully quit the editor.
OpenCode shows 0 Zephex tools
Common
1
OpenCode expects command as a single string array, not separate command + args fields.
2
Run npx -y zephex@latest setup --opencode — setup writes the correct shape.
3
If you edited by hand, merge to: "command": ["npx", "-y", "zephex@latest"] with ZEPHEX_API_KEY in env.
4
Delete any old type: local block — partial merges leave the wrong transport active.
5
Restart OpenCode after saving ~/.config/opencode/opencode.json.
Works in one folder but not another (project shadow)
Common
1
Project-level configs override global: .vscode/mcp.json, opencode.json, .mcp.json, .cursor/mcp.json in the repo root.
2
Global setup (default) writes user-level paths and removes project shadows — run npx -y zephex@latest setup without --project.
3
Check npx -y zephex list — shows which config files reference Zephex on this machine.
4
Remove stale project entries manually or run setup globally again.
5
Do not commit API keys in project MCP files to git.
Same bug every time — old npm cache or stale CLI
Common
1
Always use npx -y zephex@latest — plain npx zephex can run a cached older version.
2
After npm install -g zephex, run mcpcli update --apply or npm install -g zephex@latest.
3
Do not re-run setup repeatedly while on an old version — each run can mint a new API key (free tier: max 3 keys).
4
Verify installed version: npx -y zephex@latest info or mcpcli --version.
5
Publish lag: if npm lags behind GitHub, pin zephex@x.y.z in stdio args until @latest catches up.
tools/list returns empty or Zephex missing from editor
Critical
1
Confirm config file path for your editor (see editor guide). Run npx -y zephex@latest list.
2
Restart the editor after saving config — many only load MCP on startup (Cmd+Q, not reload).
3
For stdio: ensure npx works in a terminal (which npx) and ZEPHEX_API_KEY is in the env block.
4
For HTTP: URL must be https://zephex.dev/mcp with Authorization: Bearer YOUR_KEY.
5
Open a new agent chat after restart — Antigravity and Warp cache MCP from the previous session.
6
Run npx -y zephex@latest doctor then repair before re-running setup.
401 Unauthorized — invalid or missing API key
Critical
1
Key must start with your issued prefix (mcp_sk_ or mcp_prod_...). Revoked keys fail instantly.
2
HTTP transport: header must be Authorization: Bearer YOUR_KEY (no quotes around the key).
3
Stdio transport: ZEPHEX_API_KEY belongs in the env block inside mcp.json — not only in your shell profile.
4
If the key was committed to git, revoke it in Dashboard → API Keys and create a new one.
5
Run npx -y zephex@latest reconnect --cursor (or your editor flag) to rewrite config with a fresh key.
429 Rate limit exceeded
Critical
1
1 request = 1 tool call. Heavy agent sessions burn quota fast — check npx -y zephex@latest usage.
2
Plan limits: Free (555 req/mo), Pro (3,500 req/mo), Max (10,000 req/mo). Limits reset at the start of each calendar month.
3
Read the Retry-After header from the API response and wait before retrying.
4
Share your referral link for +300 bonus requests or upgrade at /pricing.
5
Split work across keys only if you have separate plans — keys on the same account share monthly quota.
Continue — YAML or project JSON not loading
Common
1
Continue supports ~/.continue/config.yaml (global) and .continue/mcpServers/zephex.json (project).
2
Run npx -y zephex@latest setup --continue — writes the correct block for your layout.
3
If you edited YAML by hand, ensure the zephex server block uses stdio command npx with args ["-y", "zephex@latest"].
4
disconnect --continue removes both YAML and project JSON paths.
5
Restart Continue after config changes — MCP loads at session start.
Hermes — config.yaml missing Zephex or wrong env
Common
1
Hermes is global-only: ~/.hermes/config.yaml (not project-scoped).
2
Setup writes a YAML mcpServers block with ZEPHEX_API_KEY in env.
3
disconnect --hermes strips the Zephex block and runs removeHermesEnvKey for stray .env entries.
4
Run npx -y zephex@latest setup --hermes then doctor.
5
Do not mix HTTP url and stdio command in the same zephex entry.
Kilo Code — jsonc format or 0 tools
Common
1
Kilo uses kilo.jsonc with an mcp parent key — not standard mcpServers JSON.
2
Paths: ~/.config/kilo/kilo.jsonc (global) or ./kilo.jsonc / .kilo/kilo.jsonc (project).
3
Run npx -y zephex@latest setup --kilo — setup and repair know jsonc shape.
4
list shows every Kilo path Zephex touched on this machine.
5
disconnect --kilo removes all three path variants when present.
Google Antigravity — setup ran but not connected
Common
1
Antigravity is global-only: ~/.gemini/antigravity/mcp_config.json — setup does not write project-level Antigravity config.
2
CLI setup writes stdio (command npx, args, env) — not serverUrl. Do not mix both blocks for the same zephex entry.
3
Fully quit Antigravity, reopen, start a new agent session (old sessions cache MCP).
4
Verify: ⋯ menu → Manage MCP Servers → zephex should show connected; View raw config to confirm JSON.
5
Run npx -y zephex@latest setup --antigravity then npx -y zephex@latest doctor.
6
Optional manual HTTP: serverUrl https://zephex.dev/mcp + Bearer header — remove stdio block if you switch.
Works locally but not for teammate
Common
1
Hosted MCP removes machine drift — both should use the same endpoint + key policy.
2
Do not commit API keys to git. Use per-user keys.
3
See /docs/team-rollout for rollout patterns.
WHY NO curl | bash INSTALLER?
Zephex uses npx zephex or npm install -g zephex — not a shell pipe installer like Composio. MCP setup means writing local editor JSON plus optional browser OAuth, not installing a system daemon. npx is the standard MCP CLI pattern: no root, cross-platform, no PATH surgery. A bash installer would still end up calling npm or documenting npx — marginal value. See install methods for all six paths.