A step-by-step guide to integrating Windsurf (an AI-native IDE with the Cascade agentic assistant) with CircleCI via the Model Context Protocol (MCP). Covers setting up a CircleCI account, generating API tokens, configuring the CircleCI MCP server in Windsurf, and using Cascade to validate configs, trigger pipelines, analyze build failures, inspect test results, and identify flaky tests—all without leaving the editor. Also includes troubleshooting tips for common MCP connection and authentication issues.
Table of contents
This tutorial covers:Before you startWhat makes Windsurf differentFinding your way around WindsurfWhy CI matters for AI-assisted developmentGetting started with CircleCISetting up a CircleCI projectWiring up the CircleCI MCP serverChecking your configuration before you pushStarting pipelines from your editorFiguring out why builds failDigging into test resultsUsing the CircleCI CLI through CascadeTroubleshootingPulling it all together203 Impressions