Windsurf

MCP server for Windsurf (Cascade)

Zephex is a hosted MCP server: one API key, ten tools for your real codebase—context, search, package checks, architecture maps. This page is for Windsurf users adding MCP to Cascade without running a local Node MCP process on every machine.

Windsurf reads MCP from a global file only: ~/.codeium/windsurf/mcp_config.json. A config file inside a repo folder will not work.

What tools do you get?

get_project_context — Full project snapshot: stack, deps, scripts, and config markers in one call.
read_code — AST-based symbol and file reading — no whole-file dumps.
find_code — Ranked search across the repo for definitions and usages.
check_package — Live registry safety check before installing unknown packages.
audit_package — CVEs, breaking changes, and migration notes between versions.
explain_architecture — Mermaid diagrams for how services and modules connect.
scope_task — Task description → minimal file set with risk ratings.
audit_headers — Grade deployed URLs for CSP, HSTS, TLS, and cookies.
keep_thinking — Structured multi-step debugging that remembers conclusions.
Zephex_dev_info — Expert patterns for auth, DB, frontend, and deployment topics.

All tools →

How does Zephex connect in Windsurf?

Cascade calls your MCP config over HTTPS to https://zephex.dev/mcp with a Bearer API key. No npx command block—use serverUrl, not url or command.

Developer
    │
    ▼
Cursor / Claude Code / VS Code  (MCP client)
    │
    ▼
npx zephex  (stdio bridge)  OR  HTTPS + Bearer
    │
    ▼
https://zephex.dev/mcp  (hosted MCP server)
    │
    ▼
10 tools: get_project_context, find_code, read_code,
          check_package, audit_package, explain_architecture, …

How do I add MCP to Windsurf?

Create an API key at zephex.dev.
Open or create ~/.codeium/windsurf/mcp_config.json.
Paste the zephex block with serverUrl https://zephex.dev/mcp and Authorization Bearer your_key.
Fully quit Windsurf and reopen.
Open Cascade → confirm zephex shows 10 tools.
With a repo open, ask: “Run get_project_context on this project.”

What goes wrong most often?

Config saved under the project instead of ~/.codeium/windsurf/.
Used url instead of serverUrl (Windsurf remote shape).
Left an old npx stdio block—duplicate zephex entries show 0 tools.
Project tools need a path or github:owner/repo in the prompt (global MCP does not auto-scope).

MCP troubleshooting · MCP Q&A

Windsurf vs Cursor for MCP

Cursor can use per-project .cursor/mcp.json. Windsurf is global-only—great for one key across all repos on a machine; use team key rotation if the laptop is shared. Many developers run Zephex in both editors with the same API key policy.

Cursor MCP guide · Cursor + hosted MCP

Get API key Windsurf guide