Platform
Use this page when your editor is running directly on macOS and you want the right file paths, shell checks, and restart habits before you dive into editor-specific docs.
HOSTED ENDPOINT
Zephex always uses https://zephex.dev/mcp with the same Bearer header. The operating system only changes file paths, restart flow, and shell commands.
WHAT CHANGES
Repo-local editors still use project files such as .cursor/mcp.json and .vscode/mcp.json, while machine-wide editors use files under your macOS home directory such as ~/.claude.json or ~/.codeium/windsurf/mcp_config.json.
PLATFORM SUMMARY
On macOS, Zephex setup is usually straightforward because every editor can reach the same hosted MCP endpoint over HTTPS. The mistakes that matter are almost always path mistakes, user-home confusion, or a partial restart that leaves the old tool list cached.
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 | 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.sh~/.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
REQUIRED
RULE OF THUMB
If the editor runs on this operating system, keep the config on this operating system too. If the editor actually runs in WSL, SSH, or a container, follow the guide for that runtime instead of the host desktop.
Use the path that matches the editor process running on your Mac. Project-root paths stay inside the repo. Home-directory paths live under your macOS user account.
| Editor | Location | Scope | Notes |
|---|---|---|---|
| Cursor | .cursor/mcp.json | Project | Create the .cursor folder in the repo root if it does not exist yet. |
| VS Code | .vscode/mcp.json | Project | Keep the file inside the currently opened workspace root. |
| Claude Code | ~/.claude.json | User | The tilde expands to /Users/your-name on macOS. |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | User | Create the parent folders first if they do not exist. |
| JetBrains | Settings → AI Assistant → MCP Servers | App UI | JetBrains uses a settings screen instead of a dotfile. |
Run this from Terminal on the same Mac. It confirms DNS, TLS, your API key, and the hosted tool list before you debug editor UI behavior.
DEBUG RULE
If this request succeeds but the editor still shows 0 tools, your API key and network are fine. The remaining problem is the editor config location, JSON shape, or restart flow.
mkdir -p "$HOME/.codeium/windsurf" curl -X POST "https://zephex.dev/mcp" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'After the terminal check works, verify the editor itself with a full restart instead of trusting a warm session.
These pages cover the exact JSON shape, restart flow, and UI verification steps for each editor after you have picked the right file location for this operating system.
| Editor | Use This When | Guide |
|---|---|---|
| Cursor | Best when you want the exact .cursor/mcp.json shape and restart flow. | Open guide → |
| VS Code | Use this if you want prompt-based API key input in .vscode/mcp.json. | Open guide → |
| Claude Code | Use this if your config lives in ~/.claude.json across all repos. | Open guide → |
| Windsurf | Use this if you want the exact global mcp_config.json format. | Open guide → |
| JetBrains | Use this for IntelliJ, WebStorm, PyCharm, and other AI Assistant setups. | Open guide → |
If the editor is running under a different macOS user account, files in your own home directory will be ignored. Verify the active account and keep the config under that user's home folder.
Window reloads or closing one tab are not enough for some editors. Quit the application fully, reopen it, and start a fresh session so the MCP config is reloaded.
If you pasted from a rich-text source, replace curly quotes with plain ASCII quotes and remove any comments or trailing commas before saving the JSON.
That usually means the endpoint and key are valid. Recheck the exact config file location and the editor-specific JSON shape instead of rotating the key first.
If the platform setup still does not connect, return to Quickstart or check Connection Issues.