How to Use the CircleCI MCP in Windsurf

Let Windsurf's Cascade agent run your CircleCI pipelines. Trigger builds, check status, and debug jobs without leaving your editor.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect CircleCI MCP to Windsurf

Create your Vinkius account to connect CircleCI to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup CircleCI with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Kick off builds from a prompt

This server gives your agent a `trigger_cci_pipeline` tool. You tell Windsurf to start a build, and it kicks off a new pipeline on CircleCI for any branch or tag you specify. It's a direct line from your intent to a running build. But here's where it gets interesting with Cascade. Windsurf can chain that action. It can trigger the build, then use `get_workflow_details` to wait for it to finish, and finally report the outcome. This is where an MCP server really shines—it turns a multi-step manual process into a single command.

See what's happening in any build

Stop hunting for that one failed test in the CircleCI web UI. Just ask Windsurf, "What failed in the last build?" Your agent uses this MCP server to fetch the data, giving you a straight answer right in your IDE. It's a much faster feedback loop. You can get a list of all jobs with `list_workflow_jobs`, then get specifics for any one of them using `get_job_details`. This lets you pinpoint errors without ever switching context. The tools `list_cci_pipelines` and `list_pipeline_workflows` also help you navigate from a high-level view down to the details.

Manage CircleCI with your MCP Server

This isn't just about running builds. The server also includes tools for managing your CircleCI setup. For instance, `list_cci_contexts` shows you all the shared environment contexts in your organization. It's a quick way to check if the right secrets are available before you trigger a sensitive workflow. You can also check who you're authenticated as with `get_my_cci_profile`. It's a simple tool, but useful for confirming you're operating with the right permissions, especially when you belong to multiple organizations on CircleCI.

Setup guide

Set up CircleCI MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the CircleCI MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my CircleCI payment history." If connected, Cascade will call the CircleCI tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "circleci-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by CircleCI. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect CircleCI now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about CircleCI MCP in Windsurf

Windsurf uses its Cascade agent to autonomously chain actions. You don't just trigger a build; you can tell it to trigger, monitor, and report on the build's success or failure in one go. It plans and executes the steps for you.

Yes, that's a primary use case. Ask Windsurf to investigate a failed build. It can use `list_pipeline_workflows` to find the failing workflow, then `list_workflow_jobs` to isolate the specific job, and finally `get_job_details` to pull the error.

Just open the command palette and tell Windsurf what you want. For example: "Trigger the `main` branch pipeline for the `webapp` project." It will find the `trigger_cci_pipeline` tool and execute it with the right parameters.

It returns basic information about the authenticated CircleCI user account. This typically includes your user ID, login name, and full name. It's useful for verifying the identity tied to the API token you're using.

This MCP server only accesses CircleCI metadata related to your pipelines, workflows, jobs, contexts, and user profile. Your CircleCI token is encrypted and handled by Vinkius's infrastructure, which isolates every request in an ephemeral sandbox. The server itself doesn't store any of your data.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript