I’ve been using Windsurf since the early days, and honestly? It’s changed how I write code. Not in the transformative way marketing decks promise, but in the quietly practical ‘my workflow actually makes sense now’ way.
Let me walk you through what actually happens when you connect Windsurf’s AI assistant (Cascade) to your dev tools through MCP servers. No fluff, just what worked for me.
What is MCP Anyway?
MCP (Model Context Protocol) is basically the missing link I didn’t know I needed. Before MCP, my AI coding assistant lived in a bubble—it could only see my code files. With MCP, Cascade can talk to GitHub, Linear, Slack, whatever. It’s like giving your AI assistant API access to your entire workflow. Think of it this way: without MCP, asking Cascade to “create an issue for this bug” meant it would write out the issue description, and then I’d copy-paste it into GitHub. With MCP? Cascade just creates the issue directly, while I’m still typing.
What is Windsurf?
Windsurf is an AI-first IDE built by Codeium—not VS Code with AI bolted on, but designed from scratch around an AI assistant called Cascade. Think of Cascade as a pair programmer who actually understands your entire codebase, not just the file you’re currently staring at. It can make coordinated changes across multiple files, implement features end-to-end, debug by analyzing patterns across your code, and—this is the key part—integrate with external tools through MCP. Unlike traditional autocomplete tools that just suggest the next line, Cascade works more like a teammate: you give it high-level instructions (“implement password reset with email verification”), and it breaks down the task, writes the code, creates tests, and handles the details.
My Setup: Before and After
Before Windsurf
My typical day looked like:
- Write some code in VS Code
- Alt-tab to GitHub to create an issue
- Alt-tab to Linear to link it
- Alt-tab back to my IDE
- Forget what I was doing
- Spend 5 minutes getting back into flow state
- Repeat 20 times a day
Time wasted on context switching: probably 2-3 hours daily. Not even joking.
After Windsurf + MCP
Now it’s more like:
Me: "There's an auth bug in the login flow. Fix it and create a PR."
Cascade:
- Finds the bug (token storage issue in auth.js and session.ts)
- Fixes it across both files
- Writes a regression test
- Creates a GitHub PR with a detailed description
- Links a Linear issue for tracking
- Adds proper labels and assigns it to me
Time: ~3 minutes of my actual attention
The first time this happened, I just sat there thinking “okay, this is actually wild.”
Real Numbers from Six Months of Use
I’m not one for hyperbole, but here’s what changed:
Features: Used to take me 4-5 hours end-to-end. Now? About 90 minutes. Cascade handles the boilerplate, I handle the architecture.
Bug fixes: From an hour of investigation + fix + PR creation to about 15 minutes total. The AI is weirdly good at pattern matching across files.
Code reviews: Cut in half. Cascade reads the PR, adds inline comments on GitHub, flags the actual issues. I just review its review and add context.
Issue management: This one’s super fast. What used to take 10-15 minutes of writing descriptions and linking things now takes one sentence to Cascade.
Best part? I’m not coding more. I’m just using those hours for stuff that actually moves the needle instead of mechanical busywork.
Setting This Up (The Actual Technical Part)
Alright, enough storytelling. Here’s how to make this work.
What You Need
- Windsurf IDE (grab it from codeium.com/windsurf)
- Node.js v16+
- API tokens for whatever you’re connecting
The Config File
Windsurf stores MCP configs at ~/.codeium/windsurf/mcp_config.json
. Create it if it doesn’t exist.
GitHub Setup
First, grab a GitHub token:
- GitHub Settings → Developer settings → Personal access tokens
- Generate new token (classic)
- Check these scopes:
repo
,read:org
,user
,workflow
- Copy the token
Then add this to your mcp_config.json
:
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_TOKEN": "ghp_your_actual_token_here"
}
}
}
}
The npx -y
bit means it’ll auto-install the MCP server package without asking. Saves a step.
Linear Setup
Linear’s easier—it uses OAuth, so no manual token needed:
{
"mcpServers": {
"linear": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.linear.app/sse"
]
}
}
}
First time you use it, you’ll get prompted to authenticate in your browser. Do that, and you’re done.
Complete Config
Here’s both together:
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
},
"linear": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.linear.app/sse"
]
}
}
}
Restart Windsurf, and you should be good.
Testing It
Ask Cascade something simple:
- “List my recent repos”
- “Show me open issues in your-repo”
- “What Linear issues are assigned to me?”
If it works, you’re done. If not, check the troubleshooting section below.
What You Can Actually Do With This
Cross-Platform Workflows
This is where it gets cool. Instead of managing GitHub and Linear separately:
"Create a Linear issue for implementing dark mode,
then create a GitHub branch for it and link them"
Cascade does all of it. Issue created, branch made, linked in both places.
Automated PRs
"Create a PR for this feature with a proper description
based on our conversation. Add the 'feature' label and
assign it to Sarah."
PR appears on GitHub with everything filled out. Description actually makes sense because Cascade was there for the whole conversation.
Code Review at Scale
"Review PR #234. Check for security issues and
performance problems. Add inline comments."
Cascade reads every changed file, adds comments directly on GitHub where it finds issues. Your job becomes reviewing its review, not doing the initial pass.
The Stuff That’s Not Perfect
Real talk: this isn’t magic. Some things I learned the hard way:
Token management is annoying. You need to keep these tokens secure, rotate them periodically, and if you screw up the scopes, stuff breaks in weird ways.
There’s a learning curve. The first week, I over-specified everything: “create a GitHub issue in the repository called my-repo with the title ‘Bug: Login fails’ and add labels ‘bug’ and ‘high-priority’…” Eventually you figure out Cascade can infer most of that.
Rate limits exist. GitHub caps you at 5,000 API calls per hour. Sounds like a lot until you’re having Cascade do a deep codebase analysis. Just something to know.
OAuth prompts can be janky. Sometimes Linear’s OAuth flow gets confused if you have multiple workspaces. Usually restarting Windsurf fixes it.
But honestly? These are minor compared to never manually creating another issue.
Troubleshooting Common Issues
“Authentication failed”
Check your token scopes. Seriously, 90% of auth issues are missing scopes. Regenerate the token with all the permissions listed above.
“Command not found: npx”
Install Node.js. The MCP servers run on Node, so you need it.
MCP server not loading
Validate your JSON syntax. One missing comma will break everything. Use a JSON validator if you’re not sure.
Linear won’t authenticate
Make sure popups aren’t blocked in your browser. The OAuth flow opens a new window.
Security Stuff You Should Know
Don’t be dumb with tokens:
- Never commit
mcp_config.json
to git. Add it to.gitignore
immediately. - Lock down the file permissions:
chmod 600 ~/.codeium/windsurf/mcp_config.json
- Use minimal scopes. Don’t give admin:org unless you actually need it.
- Rotate tokens every few months.
Beyond GitHub and Linear
You can add other MCP servers too. I’ve got one for Slack notifications and another for Postgres queries during debugging:
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token",
"SLACK_TEAM_ID": "T01234567"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db"
}
}
}
}
The filesystem MCP server is useful for working with files outside your project directory.
Why This Actually Matters
I’ve tried a lot of AI coding tools. Most add a feature here, a suggestion there. Windsurf with MCP is different because it removes entire categories of work from my day. I’m not copy-pasting between tools anymore. I’m not writing boilerplate PR descriptions. I’m not manually linking issues to commits. I’m not context switching myself into oblivion. Instead, I’m architecting features, solving actual problems, and occasionally watching in mild disbelief as Cascade handles the mechanical stuff I used to spend hours on. Is it perfect? No. Will it replace you? Also no. But will it make you significantly more productive while reducing the soul-crushing parts of development? Yeah, actually. The setup takes 30 minutes. The ROI is somewhere in the first week. For me, it’s been one of the best investments in my workflow in years. If you’re tired of juggling twelve tools to ship one feature, give this a shot. Worst case, you spend half an hour on setup. Best case, you get a few hours of your life back every week.