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.
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.