Platform
Use this page when your editor runs on Linux and you want the right home-directory paths, shell verification flow, and common Linux-specific failure modes before reading the editor page.
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
Linux usually uses the same repo-local paths as macOS for Cursor and VS Code, plus user-level dotfiles such as ~/.claude.json and ~/.codeium/windsurf/mcp_config.json for global setups.
PLATFORM SUMMARY
On Linux, Zephex behaves the same way it does everywhere else: one hosted HTTPS endpoint and one Bearer token. The typical problems come from permissions, home-directory mixups, or editors running in a different user session than the shell you used to edit the config.
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).Linux (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.
~/.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 these paths when the editor process runs on Linux. If you are using remote SSH, Docker, or Codespaces, edit the config inside that Linux environment rather than on your local host.
| Editor | Location | Scope | Notes |
|---|---|---|---|
| Cursor | .cursor/mcp.json | Project | Keep the file in the repo root opened by Cursor on Linux. |
| VS Code | .vscode/mcp.json | Project | This is still workspace-local even when you use a remote folder. |
| Claude Code | ~/.claude.json | User | Make sure you edit the same Linux user's home directory that runs Claude Code. |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | User | Create the parent directories before saving the file if needed. |
| JetBrains | Settings → AI Assistant → MCP Servers | App UI | JetBrains still stores the MCP server through the settings UI. |
Run this in a Linux shell on the same machine or VM as the editor. It confirms the endpoint, auth header, and tool discovery path before you troubleshoot the UI.
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 shell request works, confirm the editor is reading the config from the same Linux environment.
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 | Use this if you want the exact native HTTP config format for .cursor/mcp.json. | Open guide → |
| VS Code | Use this for prompt-based API key input in .vscode/mcp.json. | Open guide → |
| Claude Code | Use this if you want one server entry available across multiple repos for the same Linux user. | Open guide → |
| Windsurf | Use this for the exact global config format under ~/.codeium/windsurf. | Open guide → |
| JetBrains | Use this for IntelliJ-based IDEs with AI Assistant MCP settings. | Open guide → |
On Linux this is common with sudo, remote sessions, or desktop launchers. Confirm the effective user account and keep the config in that user's home directory.
If the editor runs over SSH, in a container, or in Codespaces, the local ~/.claude.json or local project root is irrelevant. Edit the config inside the remote Linux environment instead.
Make sure the current Linux user can read the config file and traverse the parent directories. Incorrect ownership or restrictive permissions can make the file effectively invisible.
That often means the editor is running in a different namespace, container, or network context. Recheck where the process actually lives before you blame the key or endpoint.
If the platform setup still does not connect, return to Quickstart or check Connection Issues.