Getting started with Windsurf and CircleCI

AI coding assistants are transforming how developers write software. Tools like Windsurf can generate entire modules, refactor complex code, and fix bugs in seconds. But speed comes with a tradeoff: AI-generated code can introduce subtle bugs, security vulnerabilities, or breaking changes that slip past even experienced developers.

That’s where continuous integration comes in. CI acts as a safety net, automatically testing every change before it reaches production. When you’re generating code faster than ever, you need validation that keeps pace. The combination of an AI coding assistant and a solid CI pipeline gives you both velocity and confidence.

This guide walks you through setting up Windsurf, connecting it to CircleCI, and creating a workflow where you can write, test, and ship code without ever leaving your editor.

Before you start

You’ll need to have a few things in place:

• A CircleCI account (the free tier handles everything in this tutorial)
• A GitHub account
• Node.js 18 or newer
• Windsurf installed on your machine

What makes Windsurf different

If you haven’t tried Windsurf yet, it’s an AI-native IDE built by the team behind Codeium. Unlike traditional editors with AI bolted on as an afterthought, Windsurf was designed from the ground up around an AI-first philosophy. The star of the show is Cascade, an agentic AI assistant that lives in your sidebar and can do far more than just autocomplete.

What sets Cascade apart is its deep awareness of your codebase and your actions. It tracks what files you’re editing, what commands you’re running, even what’s on your clipboard, all to understand your intent and stay aligned with what you’re actually trying to accomplish. It can generate entire modules, refactor existing code, and fix linting errors automatically.

Most importantly for our purposes, Cascade supports MCP (Model Context Protocol), which lets you extend its capabilities by connecting to external services. Once we hook it up to CircleCI, Cascade will be able to pull build logs, trigger pipelines, and analyze test failures as naturally as it reads your code.

Finding your way around Windsurf

If you’re new to Windsurf, here’s a quick orientation before you begin setup.

Opening Cascade

Cascade is your AI assistant panel—it’s where you’ll have conversations and issue commands. To open it:

• Keyboard shortcut: Press Cmd+L (Mac) or Ctrl+L (Windows/Linux)
• Click the icon: Look for the Cascade icon in the top-right corner of the Windsurf window

Once open, Cascade appears as a panel on the right side of your editor. Any text you’ve selected in your code or terminal automatically gets included in your conversation, which is handy for asking questions about specific code.

Cascade’s two modes

Cascade operates in two modes you should know about:

• Code mode: For creating and modifying files in your project
• Chat mode: For answering questions about your code or general programming concepts

The mode switches automatically based on what you’re asking, but you can also toggle it manually if needed.

Why CI matters for AI-assisted development

AI coding assistants excel at generating code quickly, but they don’t inherently understand your project’s constraints, test requirements, or deployment environment. A function that looks correct in isolation might break integration tests, introduce a security flaw, or conflict with existing code patterns.

CI provides the feedback loop that catches these issues. Every time you push code, whether you wrote it manually or generated it with AI, your CI pipeline runs your test suite, checks for linting errors, and validates that everything still works together. This is especially valuable when you’re iterating quickly with AI assistance, since more code changes mean more opportunities for something to slip through.

Think of CI as your automated code reviewer that never gets tired and checks every single change. It won’t catch everything, but it catches enough to make AI-assisted development practical at scale.

Getting started with CircleCI

Setting up CircleCI takes just a few minutes. Here’s the quick path:

1. Sign up: Create a free account at circleci.com. The free tier includes plenty of build minutes to get started.
2. Connect your repository: Link your GitHub, GitLab, or Bitbucket account and select the project you want to build.
3. Add your config: CircleCI looks for a .circleci/config.yml file in your repository. You can start with a simple configuration like this:

version: 2.1
jobs:
  build-and-test:
    docker:
      \- image: cimg/node:18.0
    steps:
      \- checkout
      \- run: npm install
      \- run: npm test
workflows:
  main:
    jobs:
      \- build-and-test

1. Push and watch: Commit your config file and push. CircleCI automatically detects the change and runs your first pipeline.

For a complete walkthrough with more configuration options, see the CircleCI Quickstart Guide and Configuration Introduction.

Setting up a CircleCI project

To make this integration useful, we need a project with some CI/CD history: builds that have run, tests that have executed, maybe a failure or two we can investigate. You can either fork a demo repo or use something you’re already working on.

Fork the demo repository

If you want a quick path to follow along, fork this ecommerce project that comes pre-configured with CircleCI:

1. Go to github.com/rogerwintercircleci/smarter-testing-ecommerce and fork it
2. Open CircleCI and head to Projects
3. Find your fork and click Set Up Project
4. Let the initial pipeline run

Bring your own project

If you’ve already got a project connected to CircleCI, that works great. Just make sure:

• You have a .circleci/config.yml in place
• The project appears in your CircleCI dashboard
• There are some pipeline runs in the history

Wiring up the CircleCI MCP server

The CircleCI MCP server is the bridge that lets Cascade talk to CircleCI’s APIs. It exposes CircleCI’s functionality iin a way that Cascade can understand and use. Configuration takes just a couple of minutes.

Generate your API token

First, create an API token that will authenticate Windsurf with CircleCI:

1. Log into CircleCI
2. Click your avatar in the lower-left corner
3. Navigate to User Settings
4. Go to Personal API Tokens
5. Hit Create New Token
6. Name it something you’ll recognize, like “Windsurf Cascade”
7. Copy the token right away (CircleCI won’t show it again)

Add the MCP configuration

Windsurf stores MCP server configurations in a JSON file. The easiest way to access it is through Cascade:

1. Open Cascade by pressing Cmd+L (Mac) or Ctrl+L (Windows/Linux)
2. Click the MCP icon (looks like a plug) in the top-right of the Cascade panel
3. This opens the mcp_config.json file directly in your editor

Or you can create the file manually from the command line:

On macOS or Linux:

mkdir -p ~/.codeium/windsurf
nano ~/.codeium/windsurf/mcp_config.json

On Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codeium\windsurf"
notepad "$env:USERPROFILE\.codeium\windsurf\mcp_config.json"

Add the CircleCI server configuration

Add this configuration to the file, replacing the token with your actual value:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token-here"
      }
    }
  }
}

For enhanced security, instead of hardcoding your token, you can use environment variable interpolation:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${env:CIRCLECI_TOKEN}"
      }
    }
  }
}

Then set the environment variable in your shell profile:

export CIRCLECI_TOKEN="your-circleci-token-here"

Note: Cascade can access up to 100 tools at a time across all your MCP servers. If you have many servers configured, you can toggle individual tools on or off in each server’s settings page to stay within the limit.

Check the server status

Before testing with a real query, verify that the CircleCI server connected successfully:

1. Open Cascade (Cmd+L or Ctrl+L)
2. Click the MCP icon (the plug) in the Cascade panel
3. You should see “circleci” listed among your configured servers

If it appears in the list, the connection is working. If it shows an error or doesn’t appear at all, double-check your configuration file for JSON syntax errors and make sure your API token is correct.

Test with a real query

Confirm Cascade can actually talk to CircleCI. Open Cascade and ask:

What CircleCI projects am I following?

If Cascade returns a list of your projects with their slugs (formatted like gh/your-username/your-repo), the integration is live and ready to use. If you get an authentication error, your API token may be invalid—try generating a fresh one from CircleCI.

Checking your configuration before you push

One of the most immediately practical things you can do with this integration is validate your CircleCI config without leaving Windsurf. No more discovering YAML errors after you’ve already pushed.

Ask Cascade:

Is my CircleCI configuration valid?

Cascade reads your .circleci/config.yml and checks it against CircleCI’s validation rules. You’ll get back specific feedback: whether it passes, what errors exist (with line numbers), and suggestions for improvement.

This saves real time when you’re working on complex pipelines or experimenting with new orbs.

Starting pipelines from your editor

This is one of those quality-of-life improvements that adds up fast. Rather than switching to your browser to trigger a build, just ask Cascade:

Kick off a pipeline for my current branch

Cascade reads your Git context and triggers the appropriate build. You’ll get confirmation along with a link if you want to monitor progress in the dashboard.

You can get more specific, too:

Run the pipeline for the staging branch

Or target another project entirely:

Start a build for gh/my-org/api-service on main

When you’re in the middle of debugging something and running the pipeline repeatedly, being able to trigger builds without context-switching keeps you focused.

Figuring out why builds fail

Here’s where this integration really earns its keep. When something goes wrong, you no longer have to leave your editor to investigate.

Ask Cascade:

What went wrong with my last build?

Cascade pulls the failure logs and breaks down what happened: which job failed, which step caused the problem, the error output, and context from surrounding steps.

The real value is that Cascade doesn’t just dump logs on you—it analyzes the failure and suggests what to fix. And since you’re already in Windsurf with your code open, you can make the change immediately.

Keep iterating until it passes

You can take this further by asking Cascade to handle the whole loop:

Fix that problem and run the pipeline again. Tell me when it's green.

Cascade will update the code, trigger a new build, watch for results, and report back. If something else breaks, keep going until everything passes—all without leaving your editor.

After iterating and pushing new changes, we can see that Cascade fixed the problem with our build and it is now building green on CircleCI.

Inspect a specific pipeline

Sometimes you need to look at a particular build, maybe one from earlier today or one a colleague mentioned:

Show me what happened in this pipeline: https://app.circleci.com/pipelines/github/my-org/my-repo/789

Digging into test results

When tests fail, a simple count like “5 failures” rarely tells you what you need to know. You want specifics: which tests, what assertions failed, where in the code.

Ask Cascade:

Give me the test results from my last build

There will be test names with file locations, pass/fail status, error messages with stack traces, and timing information.

To focus on what’s broken:

Just show me the failing tests

Identifying flaky tests

Flaky tests—the ones that pass sometimes and fail other times—erode trust in your test suite and waste time on unnecessary reruns.

Are there flaky tests in this project?

Cascade analyzes test history to find tests with inconsistent behavior, giving you a prioritized list to tackle.

Using the CircleCI CLI through Cascade

The MCP server connects to CircleCI’s cloud APIs, but Cascade can also run the CircleCI CLI for local operations.

Quick local validation

Validate my config with the CircleCI CLI

This runs validation locally without API calls—fast and works offline.

Execute jobs locally

Run the test job locally using the CircleCI CLI

This spins up Docker containers that mirror CircleCI’s environment, letting you debug jobs without pushing commits.

Choosing the right tool

Method	When to use
MCP server	Fetching real build logs, checking actual pipeline status, triggering remote builds, analyzing test results
CircleCI CLI	Fast local validation, running jobs in containers, iterating on config without remote round trips

Both are available, so use whatever fits the task.

Troubleshooting

MCP server isn’t loading

If Cascade doesn’t seem to have access to CircleCI tools:

1. Check the MCP panel: Click the MCP icon (the plug) in the Cascade panel. If CircleCI isn’t listed or shows an error, there’s a configuration problem.
2. Validate your JSON: Open ~/.codeium/windsurf/mcp_config.json and check for syntax errors. Common issues include missing commas, unclosed brackets, or trailing commas after the last item. You can paste the contents into an online JSON validator to check.
3. Try the refresh button: In the MCP panel, look for a refresh button to reload servers without restarting Windsurf.
4. Check the logs: Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and search for “Developer: Show Logs” to see detailed error messages about MCP connections.
5. Confirm Node.js is installed: Open a terminal and run node --version. You need version 18 or newer.
6. Test the server manually: Run this in your terminal to see if the MCP server starts correctly:

CIRCLECI_TOKEN=your-token npx @circleci/mcp-server-circleci@latest

1. Full restart: Close Windsurf completely and reopen it. Some configuration changes require a full restart to take effect.

Can’t find your project

If Cascade doesn’t recognize your project:

1. Make sure the project is followed in your CircleCI dashboard
2. Verify your Git remote: git remote -v
3. Check that your API token has the right permissions
4. Try naming the project explicitly: Get the status of gh/my-org/my-repo

Authentication problems

If you’re getting token errors:

1. Verify the token is still valid in CircleCI’s User Settings
2. Create a fresh token and update your configuration
3. Watch for accidental whitespace or newlines in the token value

Pulling it all together

You’ve now set up a development workflow that combines the speed of AI-assisted coding with the safety of continuous integration. Windsurf and Cascade let you generate and refactor code quickly, while CircleCI validates every change before it ships.

This combination addresses the core challenge of AI-assisted development: moving fast without breaking things. Your CI pipeline catches the issues that slip past, whether they’re introduced by you or by your AI assistant. And with the MCP integration, you can investigate failures, trigger builds, and iterate on fixes without ever leaving your editor.

The workflow looks like this: write code with AI assistance, push to trigger your pipeline, ask Cascade about any failures, fix and repeat until green. No browser tabs, no context switching, no lost momentum.

Ready to get started? Sign up for a free CircleCI account and connect your first project.