Connection Issues

If you just updated your config, restart your MCP client and start a new chat.

All Editors

"Connection refused" / ECONNREFUSED

• Check proxy status: https://zephex.dev/health
• Verify URL is correct: your MCP endpoint should be https://zephex.dev/mcp
• Check firewall / VPN / corporate network policy

401 Unauthorized

• Wrong key: keys typically start with mcp_ (legacy keys may start with mcp_sk_)
• Wrong header: Authorization: Bearer YOUR_KEY
• Key revoked or expired
• Extra whitespace in the key

Tools not showing up

• Restart the client completely
• Start a new chat (some clients cache tool lists per chat)
• Wait 10–15 seconds after restart before checking tools

Editor-specific

Claude Code

• "Incompatible auth server": Claude may be expecting OAuth. This proxy uses Bearer tokens — pass the Authorization header via --header as shown in the setup guide.

npx: command not found

• Install Node.js (18+ recommended) so npx is available.

Cursor

• "Header format error": Cursor can be sensitive to header args with spaces. When using mcp-remote, use Authorization:Bearer ... (no space after the colon).
• Tools capped / missing: Cursor has a low tool cap (≈40). Disable unused tools in your dashboard/tool settings if needed.

VS Code

• "GitHub Copilot Chat required": install and sign in to GitHub Copilot (Copilot Chat) — MCP tools show up in Copilot Chat.
• If tools do not appear, run Developer: Reload Window and start a new chat.

JetBrains

• "MCP settings not found": update to an IDE version that includes MCP support (2025.1.2+; 2025.2+ recommended) and enable AI Assistant.
• If the proxy requires headers, prefer the provided STDIO + mcp-remote bridge config.

Windsurf

• Server not connecting: click Refresh in MCP Marketplace or restart Windsurf completely.
• Verify config file path (commonly ~/.codeium/windsurf/mcp_config.json).

Codex

• "No such command: codex": install the Codex CLI or use an IDE extension (it shares the same MCP config).
• If you use the TOML config, ensure the bearer token env var is set (for example: MCP_PROXY_API_KEY).

Need more help? Open the full troubleshooting guide.