Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To integrate an MCP server with Windsurf, open File > Preferences > Windsurf Settings > Manage MCPs, choose View raw config, and edit ~/.codeium/windsurf/mcp_config.json. Keep a top-level mcpServers object, add the server’s command, arguments, and environment variables, save the file, then click Refresh in the MCP controls. Cascade should then display the server’s tools.
The exact package name, authentication method, and command belong to each provider’s current documentation. The examples below use the currently documented GitHub MCP Server and Azure MCP Server routes, explain what to do when tools do not appear, and show how to keep credentials out of your project files.
What MCP integration does in Windsurf
Model Context Protocol (MCP) gives Windsurf’s Cascade client a standard way to call tools and services exposed by external servers. Windsurf does not discover arbitrary packages by itself; it reads named server definitions from mcp_config.json and starts or connects to them according to each entry.
A local server normally runs over standard input/output (stdio). Its configuration tells Windsurf which executable to launch, which arguments to pass, and which environment variables to provide. Hosted or provider-managed servers can require a different transport or sign-in flow, so copy those details from the server vendor rather than guessing fields.
Before you edit the configuration
- Install Windsurf and open a workspace where you can safely test one tool call.
- Install prerequisites required by the server, such as Node.js, Docker, a provider CLI, or an authenticated cloud account.
- Obtain the provider credential through its supported sign-in process. Plan to pass secrets through environment variables or the provider’s credential store, not through a checked-in project file.
- Have a low-risk test operation ready. For example, list a repository or query a non-production Azure resource rather than changing infrastructure.
Windsurf’s menu labels and server packages can change between releases. If your screen differs, look for the MCP management panel and the option to view its raw configuration.
Open Windsurf’s MCP configuration
- In Windsurf, select File > Preferences > Windsurf Settings > Manage MCPs.
- Select View raw config. The file Windsurf reads is
~/.codeium/windsurf/mcp_config.jsonin your home directory. - Ensure the document has exactly one top-level key named
mcpServers. Each child key is the name shown in the MCP panel.
{"mcpServers":{}}Keep the JSON syntactically valid: use double quotes around keys and string values, commas between properties, and no trailing comma after the final property. A malformed file can prevent every server from appearing.
Add a local stdio server
The generic shape for a local server is:
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "PACKAGE_NAME"],
"env": {
"EXAMPLE_API_KEY": "YOUR_KEY"
}
}
}
}Replace PACKAGE_NAME, the executable, and environment variable names with values from the server’s own documentation. Do not place a real token in a repository’s committed configuration. On a shared machine, also protect the home-directory file with normal operating-system permissions.
- Insert the server entry under
mcpServers. - Save
mcp_config.json. - Return to the MCP panel or toolbar and click Refresh. Saving alone does not reload the running configuration.
- Confirm that the named server appears and that its expected tools are listed.
- Send Cascade a minimal prompt that invokes one read-only operation, then inspect the result before attempting mutations.
Connect GitHub MCP Server
GitHub documents two supported routes. The simplest is to install GitHub MCP Server from Windsurf’s plugin store. Follow the store’s sign-in or token flow, then refresh the MCP panel and check the tools.
For a manual local setup, GitHub’s guide uses the official Docker image ghcr.io/github/github-mcp-server and passes GITHUB_PERSONAL_ACCESS_TOKEN through the environment map. A representative entry is:
{
"mcpServers": {
"GitHub MCP Server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
}
}
}
}Use the exact arguments and permissions required by GitHub’s current guide, and make sure Docker is installed and available to the user account running Windsurf. GitHub marks the npm package @modelcontextprotocol/server-github as deprecated as of April 2025, so do not use it as a current installation recommendation.
GitHub authentication and first test
- Create or select the GitHub credential recommended by the official server instructions, with only the repository permissions your task needs.
- Expose it as
GITHUB_PERSONAL_ACCESS_TOKENthrough theenvmap or your operating system’s secure environment mechanism. - Save the file and click Refresh in the MCP toolbar.
- Ask Cascade for a read-only action, such as listing issues in a repository you can access. If that succeeds, try a narrowly scoped write only after reviewing the proposed change.
Connect Azure MCP Server
Microsoft Learn’s Windsurf procedure uses the Azure MCP Server through npx:
{
"mcpServers": {
"Azure MCP Server": {
"command": "npx",
"args": [
"-y",
"@azure/mcp@latest",
"server",
"start"
]
}
}
}The Azure MCP Server uses MCP to standardize connections between AI applications and external tools and data sources so operations can be context-aware of your Azure resources. Before testing it in Windsurf, authenticate with one of the supported local toolchains: Azure CLI, Azure Developer CLI, Visual Studio, or Visual Studio Code.
Azure authentication and first test
- Complete sign-in with the Azure toolchain you use and select the intended subscription or tenant.
- Save the entry above in
mcp_config.json. - Click Refresh in the MCP controls.
- Ask Cascade for a harmless inventory operation, such as viewing resources in a test subscription. Confirm the subscription and scope in the response before requesting any change.
The JSON entry and cloud login solve different problems: the entry tells Windsurf how to start the server, while the Azure sign-in supplies permission to access resources.
Compare the GitHub and Azure setup paths
| Aspect | GitHub MCP Server | Azure MCP Server |
|---|---|---|
| Typical setup | Plugin-store installation or a manual Docker image entry | Local npx entry using @azure/mcp@latest server start |
| Authentication | GITHUB_PERSONAL_ACCESS_TOKEN passed through env or the provider’s sign-in flow |
Authenticated Azure CLI, Azure Developer CLI, Visual Studio, or Visual Studio Code |
| Maintenance source | Official GitHub server image or plugin-store listing | Microsoft’s Azure MCP package and current Learn procedure |
| Primary data and tools | GitHub repositories and account operations exposed by the server | Operations contextualized to your Azure resources |
| Important version note | @modelcontextprotocol/server-github is deprecated as of April 2025 |
Package and Windsurf labels may change; follow Microsoft’s current instructions |
Why a server appears with no tools
No server is listed
- Reopen Manage MCPs > View raw config and verify the path is
~/.codeium/windsurf/mcp_config.json. - Validate JSON syntax, especially braces, commas, quotation marks, and the exact
mcpServersspelling. - Save the file, then refresh the MCP panel. Restart Windsurf only if the panel still does not reload the file.
The server is listed, but its tools are empty
- Check that
commandand every item inargsmatch the vendor’s current example. - Confirm required software is installed and callable by Windsurf’s process. A command that works only in a different shell or user account may fail here.
- Check required credentials and any transport field specified by the server documentation. Do not add undocumented fields as a guess.
- Refresh after every edit; GitHub’s installation guide explicitly instructs users to click Refresh in the MCP toolbar.
Authentication fails
- For GitHub, verify the token value, its permissions, and that the variable is named exactly
GITHUB_PERSONAL_ACCESS_TOKEN. - For Azure, confirm that the local Azure CLI, Azure Developer CLI, Visual Studio, or Visual Studio Code session is signed in to the intended tenant and subscription.
- Keep secrets in environment variables or the provider’s sign-in flow. Remove exposed credentials and rotate them if they were committed or pasted into a shared configuration.
Instructions reference a package that no longer works
Prefer the vendor’s current official image, plugin, or package. GitHub’s old @modelcontextprotocol/server-github npm route is explicitly deprecated as of April 2025; use the GitHub plugin-store route or official Docker image instead.
Operate MCP servers safely in daily work
- Start with read-only prompts and a test repository or subscription.
- Give each server a descriptive name so Cascade’s tool list is understandable when several integrations are enabled.
- Limit tokens and cloud identities to the smallest useful scope.
- Review tool arguments before approving actions that create, delete, merge, deploy, or change infrastructure.
- After upgrading Windsurf or a provider package, recheck the vendor’s command and authentication instructions; UI labels and package names are version-sensitive.
- If a server stops responding, capture the exact error, verify the executable and credentials outside Windsurf, then refresh the MCP controls after correcting the entry.
Or skip the browser setup
If your goal is automated website capture rather than connecting GitHub or Azure, ScreenshotNeo provides a website screenshot API and an MCP server for AI agents. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP tools include take_screenshot, get_page_info, and capture_pdf, and the server works with Claude, Cursor, and any MCP client. You can use the same MCP configuration approach in a compatible client, or call the API directly.
Free tools Windows power users keep installed
One-click scans. No signup required.
API documentation: https://screenshotneo.com/docs/
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every response reports whether the page was clean and whether it was billed through the X-Page-Verdict and X-Billed headers. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Start at ScreenshotNeo’s free sign-up.
Quick Recap
Final verification checklist
- The file is
~/.codeium/windsurf/mcp_config.jsonand parses as valid JSON. - The top-level key is
mcpServers. - The server’s command, arguments, package or image, and environment names match its current official documentation.
- Credentials are supplied securely and the provider login is complete.
- You saved the file and clicked Refresh.
- The expected tools appear and a read-only test succeeds before you approve consequential actions.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
