Context7 MCP server in Windsurf fresh docs for Cascade.
Add Context7 to Windsurf's mcp_config.json and Cascade can fetch current, version-specific library documentation before it writes a line of code.
Cascade, Windsurf's agent, writes a lot of code autonomously — which makes stale library knowledge more costly here than in a chat assistant, because nobody reviews each call before it lands in your diff. Context7 (from Upstash, 57.1k stars on GitHub) gives Cascade a documentation lookup tool that returns the API surface of the version you actually have installed.
Windsurf keeps MCP configuration in one global file. Here's the entry, the refresh step people skip, and what to check when the server stays grey.
What Cascade does with it
Once connected, Cascade can resolve a library reference and pull its current docs mid-task — before scaffolding an integration, while fixing a type error caused by an upgraded dependency, or when you explicitly ask how the installed version of something works. As of mid-2026 the server exposes a resolve step and a docs-fetch step as its core tools; check the repo for the current set.
The package is plain npm, runs locally over stdio, and is free and open source.
Edit mcp_config.json
Windsurf reads servers from a single global file at ~/.codeium/windsurf/mcp_config.json — there's no per-project variant, so whatever you add is available in every workspace. You can reach the same config through Windsurf Settings > Cascade > MCP Servers > Add Server if you prefer the UI; either way the file ends up like this:
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}Refresh Cascade and confirm
Windsurf doesn't watch the config file. After saving, open the MCP servers panel in Cascade and hit refresh (or restart Windsurf outright). The server should turn green with its tools enumerated — compare against the live tool list on Context7's Loomal marketplace listing at https://loomal.ai/marketplace/context7 if you want to confirm everything loaded.
Troubleshooting in Windsurf
A server stuck in an error state after refresh usually means the npx process died on launch: try the command in a terminal, and remember Windsurf may inherit a leaner PATH than your shell — a Node version manager that's only initialized in .zshrc is a frequent cause.
Two Windsurf-specific things: the config is global-only, so a broken entry degrades every workspace at once, and Windsurf enforces a cap on the total number of active MCP tools across servers. If you run many servers and Context7's tools don't appear despite a green status, deactivate tools you don't use elsewhere and refresh again.
FAQ
How do I add Context7 to Windsurf?
Add a context7 entry under mcpServers in ~/.codeium/windsurf/mcp_config.json (command npx, args ["-y", "@upstash/context7-mcp"]), then refresh the MCP servers panel in Cascade. The Settings > Cascade > MCP Servers UI writes the same file.
Can I scope Context7 to one project in Windsurf?
No — Windsurf's MCP config is a single global file, so the server is available in every workspace. If you only want it active sometimes, toggle it in the Cascade MCP panel rather than editing the file.
I edited the config and nothing happened. Why?
Windsurf only re-reads mcp_config.json on a refresh or restart. Hit the refresh button in the Cascade MCP panel; if the server then errors, run npx -y @upstash/context7-mcp in a terminal to see the real failure.
Does Context7 charge for usage?
The server is open source and free to run locally. Context7 offers an optional API key that raises rate limits — relevant mainly for heavy automated use; see their docs for the current policy.
More MCP servers for Windsurf.
Browse the index — live tool lists on every listing.