GitHub MCP server in Windsurf Cascade meets your repos.
Windsurf's Cascade agent picks up GitHub's hosted MCP server through one entry in mcp_config.json — issues, PRs, and Actions become part of the agentic flow.
Windsurf's Cascade is built around long agentic runs, and GitHub's official MCP server (github/github-mcp-server, 30.6k stars) extends those runs past the editor boundary — Cascade can finish a task by opening the PR, commenting on the issue, or checking why a workflow failed.
The server is hosted by GitHub, so the Windsurf side is purely configuration: one JSON entry in mcp_config.json and a refresh in Cascade's settings.
One global config file
Unlike Cursor or VS Code, Windsurf keeps a single global MCP config with no per-project variant: ~/.codeium/windsurf/mcp_config.json (the .codeium directory is inherited from Windsurf's Codeium lineage). Every workspace shares it, which suits a GitHub connection fine — you generally want repo access everywhere.
You can reach the file two ways: edit it directly, or open Windsurf Settings > Cascade > MCP Servers and use Add Server, which writes to the same file.
The config entry
Windsurf uses serverUrl (not url) for remote servers — a small but load-bearing difference from other clients' config shapes:
{
"mcpServers": {
"github": {
"serverUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ghp_YOUR_GITHUB_PAT"
}
}
}
}Token scope for an agent that runs long
Cascade chains many steps without stopping to ask, so the PAT in that header is effectively the agent's blast radius. A fine-grained token restricted to the repos you'll automate, with write permission only on pull requests and issues, keeps a misfired run from becoming a mess.
Tokens live in plaintext in mcp_config.json, so keep the file out of any dotfiles repo you sync publicly, and rotate the PAT on a schedule like any other long-lived credential.
Refresh and confirm
After saving, go to Windsurf Settings > Cascade > MCP Servers and hit the refresh control — Windsurf doesn't reliably re-read the config on save alone. The github server should list with a healthy status and an expandable tool list.
Then test inside Cascade: "check whether the latest Actions run on my main branch passed." A real answer backed by a visible tool call means you're configured. The server's full tool catalog is on its live Loomal listing at https://loomal.ai/marketplace/github.
Troubleshooting in Windsurf
Server not listed after refresh: the JSON is malformed or the file is in the wrong place. Confirm the exact path ~/.codeium/windsurf/mcp_config.json — a common mistake is creating ~/.windsurf/mcp_config.json, which Windsurf never reads.
Listed but erroring: using url instead of serverUrl is the classic Windsurf-specific bug; the entry parses but can't connect. Auth failures (401) mean the header value lost its Bearer prefix or the token expired.
If tools load but Cascade won't use them, fully restart Windsurf rather than just refreshing — stale server state in a long-running session occasionally needs the heavier reset.
FAQ
How do I add the GitHub MCP server to Windsurf?
Add a github entry with serverUrl https://api.githubcopilot.com/mcp/ and an Authorization header to ~/.codeium/windsurf/mcp_config.json, then refresh in Settings > Cascade > MCP Servers. Cascade picks up the tools immediately after the refresh.
Why is my config ignored even though the JSON is valid?
Two Windsurf-specific traps: the file must live under ~/.codeium/windsurf/ (not ~/.windsurf/), and remote servers must use the serverUrl key — url parses fine but never connects. Check both before suspecting the token.
Can I configure this per project instead of globally?
No — Windsurf's MCP config is global, shared by all workspaces. If you need different GitHub access per project, the practical workaround is separate fine-grained PATs and swapping the header value, or scoping a single token to the union of repos you automate.
Does Windsurf need a restart after config changes?
Usually the refresh button in Settings > Cascade > MCP Servers is enough. If tools appear but behave stale — old tool lists, calls that hang — do a full application restart to clear the server connection state.
More MCP servers for Windsurf.
Browse the Loomal marketplace and compare live tool lists.