Installation
Setup Walkthrough — From zero to working MCP in 90 seconds
What actually happens when you run npx zephex setup. Every step diagrammed, every prompt explained, every file written.
The big picture
┌──────────────────────────────────────────────────────────────────┐ │ Your machine │ │ │ │ ┌─────────────────┐ │ │ │ You type: │ │ │ │ npx zephex │ │ │ │ setup │ │ │ └────────┬────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 1. CLI picker │ │ │ │ - Pick editor (20 options) │ │ │ │ - Pick scope (if in a project) │ │ │ │ - Pick mode (MCP / MCP+Skill) │ │ │ └────────┬────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 2. CLI hits zephex.dev/api/cli/session │ ──── HTTPS ────┐ │ │ │ Gets a session_id back │ │ │ │ └────────┬────────────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────┐ ┌────────────────┐ │ │ 3. Browser opens to │ │ zephex.dev │ │ │ zephex.dev/cli/auth?session=xxx │ ── │ (server) │ │ └────────┬────────────────────────────────┘ └────────────────┘ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 4. You sign in (GitHub or Google) │ │ │ │ Browser creates an API key │ │ │ │ Marks the CLI session complete │ │ │ └────────┬────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 5. CLI polls /api/cli/poll until done │ ──── HTTPS ────┐ │ │ │ Receives the API key │ │ │ │ └────────┬────────────────────────────────┘ ▼ │ │ │ (gets key) │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 6. CLI writes the editor config │ │ │ │ ~/.cursor/mcp.json (or equivalent) │ │ │ └────────┬────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 7. (Optional) Installs skill + rule │ │ │ │ ~/.cursor/skills/zephex/SKILL.md │ │ │ │ ~/.cursor/rules/zephex.md │ │ │ └────────┬────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ 8. Tells you to restart your editor │ │ │ └─────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────┘
Step 1 — You run the command
npx zephex setupThat's it. npx downloads the latest zephex package from npm (~1.4MB) and runs it. No global install needed.
If you don't have Node.js, see Quickstart for the manual JSON-config method.
Step 2 — The picker
The CLI shows a 3-step picker. Each step shows what it does so you don't have to guess:
The npx zephex setup wizard detects your environment and walks you through editor, scope, and mode selection.
Step 2a: Pick your editor
◆ Which editor do you want to connect?
❯ Cursor ← arrow keys to move
Claude Code ← or press 1-9, 0, a-j to jump
VS Code ← or type "c" to filter to Cursor/Claude/Cline
Codex
OpenCode
Windsurf
Zed
Warp
Gemini CLI
Kiro
Cline
JetBrains
Kilo Code
Amp
Continue
GitHub Copilot CLI
Factory Droid
Claude Desktop
Antigravity
TRAE
↑↓ navigate · enter select · type letter or [1-9,a-j] to jump · esc cancelStep 2b: Pick scope (only shown in a real project)
If your current directory has package.json, .git, pyproject.toml, etc., the CLI asks where to install:
◆ Where should Zephex be available?
❯ All projects (global)
This project only (myapp)If you're in your home directory, /tmp, or any system folder, this step is auto-skipped — Zephex installs globally.
Step 2c: Pick the agent mode
◆ How should the agent use Zephex?
❯ MCP + Skill + Rule (recommended)
MCP server onlyMCP + Skill + Rule writes additional SKILL.md and rules.md files that teach your agent when to call Zephex tools proactively.
MCP server only just writes the connection config. Tools are available but the agent decides when to call them.
Step 3 — Browser-based OAuth
The CLI opens your default browser to:
https://zephex.dev/cli/auth?session=01jx8m...The page asks you to sign in. Two methods:
- GitHub (recommended for developers)
After signing in, the page automatically:
- Creates a new API key associated with your account
- Marks the CLI session as complete with that key
- Shows "You can close this tab"
Meanwhile in your terminal:
◇ Opening zephex.dev in your browser... │ ◇ Waiting for you to sign in... (polls every 2 seconds) │ ◇ Waiting for you to sign in... │ ◇ Waiting for you to sign in...
Step 4 — The config file
Once the CLI receives the API key, it writes the editor-specific config file. The exact path depends on your editor:
Editor Global config Project config ───────────────────────────────────────────────────────────────────────────────── Cursor ~/.cursor/mcp.json ./.cursor/mcp.json Claude Code ~/.claude.json ./.mcp.json VS Code — ./.vscode/mcp.json Codex ~/.codex/config.toml ./.codex/config.toml OpenCode ~/.config/opencode/opencode.json ./opencode.json Windsurf ~/.codeium/windsurf/mcp_config.json — Zed ~/.config/zed/settings.json — Warp ~/.agents/.mcp.json — Gemini CLI ~/.gemini/settings.json ./.gemini/settings.json Kiro ~/.kiro/settings/mcp.json — Antigravity ~/.gemini/antigravity/mcp_config.json — Claude Desktop Library/Application Support/Claude/ —
Example — what the CLI writes for Cursor:
{ "mcpServers": { "zephex": { "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_prod_priv-1234.your-secret-here" } } }}Note that the format varies per editor. Codex uses TOML, VS Code uses a servers key (not mcpServers), and Antigravity uses serverUrl not url. The CLI handles all of these automatically.
Step 5 — Skill + Rule files (optional)
If you picked "MCP + Skill + Rule" in step 2c, the CLI writes two more files:
Editor Skill file path Rule file path ──────────────────────────────────────────────────────────────────────────── Cursor ~/.cursor/skills/zephex/SKILL.md ~/.cursor/rules/zephex.md Claude Code ~/.claude/skills/zephex/SKILL.md ~/.claude/rules/zephex.md OpenCode ~/.agents/skills/zephex/SKILL.md ~/.config/opencode/AGENTS.md (block) others ~/.agents/skills/zephex/SKILL.md —
The skill file teaches the agent when to call Zephex tools. Without it, tools are visible but the agent may not use them at the right times.
Step 6 — Restart the editor
The terminal prints success and tells you to restart:
◇ Signed in as you@example.com ◇ API key created: cli-2026-05-24 ◇ Config written to ~/.cursor/mcp.json ◇ Skill installed at ~/.cursor/skills/zephex/SKILL.md ◇ Rule installed at ~/.cursor/rules/zephex.md └ Done! Restart Cursor and you'll see Zephex tools in the tool list.
Important: a window reload is not enough for most editors. Quit the editor completely (Cmd+Q on Mac, fully exit on Windows/Linux) and reopen it.
Step 7 — Verify the connection
After restarting, run the live status check:
npx zephex statusExpected output:
EDITOR CONFIG KEY STATUS TOOLS DETAIL------------------ ------------------------ --------------- ------ ----- ------Cursor (global) ~/.cursor/mcp.json mcp_prod_pri... PASS 10 okIf STATUS is PASS and TOOLS is 10, your editor is connected.
What if something goes wrong?
Symptom Run this ────────────────────────────────────────────────────────────────── Browser didn't open Open the URL the CLI printed "Waiting for sign in" stuck > 5 minutes Check internet, retry setup Tools don't appear in editor Quit and reopen editor fully "401 Unauthorized" in editor npx zephex reconnect Network errors npx zephex doctor Want a clean slate npx zephex reset --all Want to see what's installed npx zephex list
For more, see Troubleshooting.
The complete flow as one timeline
0:00 You run: npx zephex setup 0:01 npm downloads zephex package (~1.4MB) 0:03 Picker appears — pick editor (Cursor) 0:08 (in a project) Pick scope — All projects 0:12 Pick mode — MCP + Skill + Rule 0:14 Browser opens to zephex.dev/cli/auth 0:15 You click "Continue with GitHub" 0:18 GitHub OAuth → back to zephex.dev 0:21 Page creates API key + marks session complete 0:22 CLI receives the key (it was polling) 0:23 CLI writes ~/.cursor/mcp.json 0:24 CLI writes ~/.cursor/skills/zephex/SKILL.md 0:24 CLI writes ~/.cursor/rules/zephex.md 0:25 "Done! Restart Cursor." 0:30 You quit Cursor (Cmd+Q) 0:35 You reopen Cursor 0:40 You ask: "find where validateToken is used" 0:41 Cursor calls find_code via MCP 0:42 Zephex returns AST-aware results 0:42 You see the results in your editor Total: ~90 seconds end to end.
What about the API key?
The key is created on your behalf during step 4. It looks like this:
mcp_prod_priv-1234.abc123def456...It's stored:
- In your editor's config file (the only place on your machine)
- As a SHA-256 hash on the Zephex server (we never see the plain text after creation)
To see all keys you have installed:
npx zephex keysTo revoke and create a new one:
npx zephex reconnectWhere to next
- CLI Commands Reference — every command, every flag
- Tool Filtering — enable / disable specific tools
- Quickstart (manual) — install without Node.js
- Supported Editors — config paths for all 20
- Troubleshooting — common issues and fixes