Windsurf MCP: Setup and Servers Worth Adding

Windsurf connects to MCP servers by launching each one as a command and exposing its tools to the agent. A windsurf mcp setup comes down to one config entry per server, such as npx -y @upstash/context7-mcp for live docs. Start with Context7, GitHub and Playwright, keep tokens read-only, and restart or refresh Windsurf when a server does not appear.

How does Windsurf connect to MCP servers?

Windsurf is an MCP client. You tell it which servers exist, and for a local server that means giving it a command to run. Windsurf starts the process, asks it which tools it offers, and lets the agent call those tools while it works in your project. A server is just a program that speaks the protocol, so the same server you run elsewhere also runs here.

That portability is the practical point. Context7's listing names Windsurf next to Claude Code, Claude Desktop, Cursor and VS Code with Copilot as compatible clients, and the Playwright server's listing shows the same pattern. Nothing about the server changes between editors; only the place where you register it does. If you already know how to add a server in another editor, you already know most of this. The explainer What Is MCP (Model Context Protocol)? covers the protocol itself.

A server exposes tools, and it can also expose resources and prompts. For daily work in Windsurf, tools matter most, because they are what the agent actually invokes. If you want the full vocabulary, MCP Tools, Resources, and Prompts Explained walks through the three.

Where does the Windsurf MCP config live?

Windsurf keeps its server list in an MCP configuration that you edit from its own settings. The exact file path and the in-app menu names are defined by Windsurf's documentation, so check that page for your version rather than copying a path from a forum post. What stays constant across clients is the shape of an entry: a server name, the command to launch, and its arguments.

A typical entry for a package-based server looks like the example below. The command and package name come from the Context7 project's install instructions, which give npx -y @upstash/context7-mcp as the direct run command. Treat the surrounding JSON keys as the common client convention and confirm them against Windsurf's documentation before saving.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Secrets belong in the entry's environment settings, not in the arguments and not in a repository. Anything you paste into a file that gets committed is effectively published. For background on why scopes matter, see MCP Server Permissions and Scopes Explained.

How do you add a server step by step?

The routine is the same for every server, so it is worth doing once carefully. Work through it with a low-risk server first, then repeat it for the rest.

1. Pick the server and read its run command. For Context7 that is npx -y @upstash/context7-mcp; for Playwright it is npx -y @playwright/mcp; for GitHub it is npx -y @modelcontextprotocol/server-github.
2. Open Windsurf's MCP configuration and add an entry with that command and its arguments, as in the example above.
3. Add any credentials the server needs to the entry's environment settings. GitHub needs a fine-grained personal access token; Context7 and Playwright do not need one according to their install instructions.
4. Save, then refresh or restart Windsurf so it launches the server and reads its tool list.
5. Ask the agent something that forces a tool call, such as asking it to open a page or list issues, and confirm the call appears.

The MCPizy CLI offers a shortcut for the install command: mcpizy install context7, mcpizy install playwright or mcpizy install github. The listings describe it as the recommended route, with the npx command as the direct alternative. If you use the direct route, you own the config entry.

Which servers are worth adding first?

Begin with servers that help in almost every coding session and carry little risk. Context7 serves live documentation for libraries and frameworks, which reduces the guessing an agent does about current APIs. It needs no account to try, so it is a good first test of your setup.

GitHub is the second pick if your code lives there. The official server ships 9 tools, including list_issues, list_pull_requests, create_pull_request and get_file_contents. The description recommends a fine-grained token with the smallest scope, read-only repository and issues access, and upgrading to write only when a human approves. A deeper walkthrough is in How to Use GitHub MCP with Claude Code, and the steps carry over.

Playwright gives the agent a real browser. It exposes 7 tools such as browser_navigate, browser_snapshot, browser_click and browser_take_screenshot. The CheckMCP audit of microsoft/playwright-mcp gives it 100/100 (grade A), 36,404 stars, an Apache-2.0 licence and 4 open issues. It suits checking that a page you just edited renders and behaves as expected. See How to Use Playwright MCP with Claude Code for usage ideas.

What does Windsurf MCP not do?

A server only gives the agent tools; it does not make those tools safe or complete. With GitHub, the description lists several pitfalls. Fine-grained tokens do not cover private repositories just because you chose all repositories, so an empty list_pull_requests result usually means the token needs that repo selected explicitly. search_code relies on an index that can lag by 5-30 min and skips some file types, so fall back to cloning and grepping when it returns fewer than 3 hits.

Writes deserve caution. The GitHub description notes that create_or_update_file commits through the API, which means no GPG signing, no pre-commit hooks and no CI run on the same commit unless branch protection allows it. For anything beyond small documentation fixes, have the agent push a branch and open a pull request instead of committing to main. Authenticated tokens are also limited to 5,000 requests per hour, so large audits across many repositories should batch or paginate.

Cost is the other limit. Every tool the agent can see adds to what it must consider, and large reads are expensive: the GitHub description puts one 1k-line file at roughly 4k tokens through get_file_contents. Add the servers you use, not every server you find, and audit unfamiliar ones first with How to Audit an MCP Server Before Install.

Why does a server not show up in Windsurf?

Most failures are small. First check that the file is valid: a missing comma or a stray quote in the configuration stops the whole list from loading. Next, confirm the command runs on its own in a terminal. If npx -y @playwright/mcp fails there, it will fail inside Windsurf too, and the terminal error message tells you whether Node, the network or the package name is at fault.

If the command works but the tools are missing, refresh or restart Windsurf so it relaunches the process and reads the tool list again. Then ask the agent a question that can only be answered with that server, for instance a library question for Context7, so you see whether the call is actually made. When the server shows but calls fail, look at credentials: a GitHub token without access to the specific repository is the documented cause of empty results.

Finally, check where the server runs. A command-based server runs on your machine and shares its environment, while a hosted one is reached over the network and behaves differently when the connection drops. Local vs Remote MCP Servers: What Changes lays out the trade-offs and what to check in each case.

Where can you browse more servers for Windsurf?

Once Context7, GitHub and Playwright work, extend the setup in the direction your project needs. For a project-management workflow, Project Management MCP Servers: Monday, Jira, Dart compares options. For testing and scraping, MCP Servers for Browser Automation goes beyond Playwright. If your issue tracker is Linear rather than GitHub, the GitHub description itself says Linear suits sprint and cycle planning better, and it names GitLab and Gitea as alternatives for other hosts.

Each server page in the directory shows its install command, tools and, where one exists, the CheckMCP audit, so you can judge licence and maintenance before adding it. Add one server at a time, confirm it shows up, and only then add the next. That keeps a broken entry easy to find and keeps the tool list the agent sees short enough to be useful.

Servers also chain well. The Issue → Branch → PR Pipeline recipe shows how GitHub can fit into a larger flow, and Visual Regression on PRs pairs Playwright with GitHub. Both are useful once the individual servers are running reliably in your editor.