To integrate the Model Context Protocol (MCP) with Windsurf, open File > Preferences > Windsurf Settings > Manage MCPs, choose View raw config, edit ~/.codeium/windsurf/mcp_config.json, add a server under the top-level mcpServers object, save, and click Refresh in the MCP controls. Cascade can then discover and call the tools that server exposes.
The exact command, arguments, credentials, and authentication flow come from each server’s current documentation. The examples below show the configuration shape and current GitHub and Azure procedures without treating them as interchangeable.
What MCP integration does in Windsurf
Model Context Protocol (MCP) gives Windsurf’s Cascade client a standard way to connect to external servers that expose tools and data. Windsurf launches or connects to the server described in its MCP configuration, discovers the available tools, and makes those tools available to Cascade.
An MCP entry is not an API definition by itself. It tells Windsurf how to start or reach a particular server. The server’s own documentation remains authoritative for package names, command-line arguments, transport settings, required environment variables, and sign-in steps.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Before you configure a server
- Install Windsurf and confirm that Cascade works normally.
- Read the provider’s current MCP installation guide. Package names and Windsurf labels can change between releases.
- Install any runtime the server requires, such as Node.js, Docker, or a cloud CLI.
- Prepare credentials through environment variables, an operating-system credential store, or the provider’s sign-in flow. Do not commit tokens to a project repository.
- Know whether the server is local (usually a standard-input/standard-output process) or hosted and requires a remote endpoint and a different transport configuration.
Open Windsurf’s MCP configuration
- In Windsurf, select File > Preferences > Windsurf Settings > Manage MCPs.
- Select View raw config. This opens the JSON file Windsurf uses for MCP definitions.
- Confirm that the file is
~/.codeium/windsurf/mcp_config.jsonin your home directory. On Windows, use the equivalent user-home path shown by Windsurf rather than creating a second file in the project. - Keep
mcpServersas the top-level JSON key. Add each server as a uniquely named property beneath it.
A minimal local-server entry has this form:
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "PACKAGE_NAME"],
"env": {
"EXAMPLE_API_KEY": "YOUR_KEY"
}
}
}
}Replace PACKAGE_NAME, the command, and the environment-variable names with values from the server’s documentation. JSON requires double quotes, commas between properties, and no trailing comma after the final property.
Add a local MCP server step by step
- Copy the server’s documented command and arguments into a new named entry. For an
npx-based server, the command is commonlynpxand the arguments include-yfollowed by the package name. - Add only the environment variables the server requires. Keep secret values out of source-controlled files; use a shell environment, an operating-system secret manager, or the provider’s login flow where supported.
- Save
mcp_config.jsonand validate that it is syntactically valid JSON. A missing comma or an extra comma can prevent every server from loading. - Return to Manage MCPs and click the Refresh control in the MCP panel or toolbar. Saving the file alone does not guarantee that Cascade has reloaded it.
- Check that the server is listed and that its expected tools appear. Send a small, read-only prompt that invokes one known operation before attempting changes or bulk actions.
Connect the GitHub MCP Server
GitHub’s official Windsurf guidance offers two supported routes:
Install from the Windsurf plugin store
Open Manage MCPs, find GitHub MCP Server in the plugin store, and follow its installation and authentication prompts. This route lets the provider maintain the launch details as they change.
Configure GitHub’s Docker image manually
The manual route uses the official image ghcr.io/github/github-mcp-server. The exact Docker arguments can change, so copy the current command from GitHub’s guide and place the required token in an environment variable. The configuration pattern is:
{
"mcpServers": {
"GitHub": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
}
}
}
}Use the current GitHub documentation to confirm the image arguments and token permissions for the operations you intend to perform. Save, click Refresh (🔄) in the MCP toolbar, and verify that the GitHub tools are listed.
Do not present @modelcontextprotocol/server-github as the current installation route: GitHub’s guide marks that npm package deprecated as of April 2025.
Connect the Azure MCP Server
Microsoft Learn documents this Windsurf entry for the Azure MCP Server:
{
"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, allowing AI systems to perform operations that are context-aware of Azure resources. Before asking Cascade to use it, authenticate with one of the methods Microsoft supports: Azure CLI, Azure Developer CLI, Visual Studio, or Visual Studio Code. The JSON entry starts the server; it does not replace Azure authentication.
- Install or update the Azure tooling required by Microsoft’s current guide.
- Sign in with the supported toolchain you selected.
- Add the entry above to
mcp_config.json. - Save and refresh the MCP controls.
- Ask Cascade for a harmless operation that reads a resource you can safely inspect, then confirm the result in Azure.
Local command versus hosted MCP servers
Use these questions when deciding how to configure another provider:
| Question | Local command | Hosted endpoint |
|---|---|---|
| How does Windsurf connect? | Starts a process such as npx or Docker and communicates over its documented local transport. |
Connects to a provider URL using the transport and endpoint fields documented by that provider. |
| Where is authentication handled? | Often an environment token or an already-authenticated CLI. | Often OAuth, an API token, or provider-managed credentials. |
| Who maintains launch details? | You must update the command, image, or package when the vendor changes it. | The provider generally controls the service, but you still manage access and endpoint settings. |
| What should you verify? | Command availability, arguments, runtime, environment, and logs. | Endpoint, transport, network access, TLS, authentication, and allowed tools. |
Never invent a transport field or URL. If a provider’s guide does not show a setting, do not add one simply because another MCP server uses it.
Why a server shows no tools
The server is not listed
Reopen Manage MCPs and View raw config. Confirm that Windsurf is reading ~/.codeium/windsurf/mcp_config.json, that mcpServers is at the top level, and that the JSON parses. A malformed entry can stop the configuration from loading.
The server is listed but exposes no tools
Check the provider’s current command, arguments, credentials, and required transport. Then save the file and refresh the MCP toolbar. A process that starts but cannot authenticate may appear differently from one that never starts, so inspect the server’s own logs or diagnostic output when available.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Authentication fails
Verify that the token is valid, has the required permissions, and is actually available to the process Windsurf starts. For Azure, complete the supported Azure CLI, Azure Developer CLI, Visual Studio, or Visual Studio Code sign-in. For GitHub, confirm the personal access token environment variable and the permissions required by the requested operation.
The command cannot be found
Run the command outside Windsurf in the same user account, check that Node.js or Docker is installed, and confirm that the executable is on the PATH visible to Windsurf. A terminal that has a custom shell profile may have a different PATH from the graphical application.
Changes appear to do nothing
Click Refresh after every edit. If the old server remains, close and reopen the MCP management view or restart Windsurf, then verify that only one entry with the intended name exists.
A package instruction is obsolete
Prefer the vendor’s current official image or package. GitHub’s explicit deprecation of @modelcontextprotocol/server-github illustrates why copied tutorials can fail even when their JSON is valid.
Security and operational practices
- Keep tokens in environment variables or provider sign-in flows, not in a checked-in configuration file.
- Grant the least privilege needed for the tools you plan to call.
- Start with read-only prompts and inspect the tool name and arguments before approving a write operation.
- Use separate credentials for development and production resources.
- Record which provider documentation and package version you used so future updates are deliberate rather than accidental.
Or skip the browser setup
If your workflow needs screenshots for documentation, testing, or an AI agent, ScreenshotNeo provides an MCP server and a one-request screenshot API at ScreenshotNeo. It accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether the request was billed.
Use the API documentation at https://screenshotneo.com/docs/ for the full option list and MCP setup. A basic cURL call is:
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}`);ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector elements, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks before capture, selector waits, delays, network-idle waits, blocking ads or resource types, custom headers and cookies, user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs, which can simplify migration.
An MCP server lets Claude, Cursor, or another MCP client call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free for ScreenshotNeo.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFinal verification checklist
- The file is
~/.codeium/windsurf/mcp_config.json. mcpServersis the top-level key and the JSON parses.- The server command, arguments, package or image, and transport match the vendor’s current guide.
- Credentials are supplied safely and the required cloud or provider login is complete.
- You saved the file and clicked Refresh in Windsurf’s MCP controls.
- The expected tools appear and a low-risk test succeeds.
Frequently Asked Questions
Can I put Windsurf MCP settings in a project file?
Windsurf’s documented user configuration is ~/.codeium/windsurf/mcp_config.json. Keep credentials out of any project file that could be committed or shared.
Does adding an MCP entry authenticate me automatically?
No. The entry starts or locates the server; GitHub tokens and Azure’s supported CLI or IDE sign-in must be configured separately.
Why should I refresh after saving mcp_config.json?
Cascade reloads the MCP definitions through the MCP controls. Saving the file without clicking Refresh can leave the previous server state active.
Quick Recap
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.
