Connecting Windsurf

Windsurf is Codeium's AI-powered IDE. It supports MCP servers via both HTTP and stdio transport.

Prerequisites

Windsurf installed (download)
A HeadlessOps account with at least one workspace

Option A: Remote MCP (Recommended)

Open Windsurf Settings → MCP and add a new server entry:

{
  "mcpServers": {
    "headlessops": {
      "url": "https://app.headlessops.ai/mcp",
      "type": "http"
    }
  }
}

Save the settings
Restart Windsurf
Authorize in the browser when prompted on first use

Option B: Local Proxy (Enables `folderPath`)

Install the local proxy to enable folderPath support for reading and writing your local integration files.

Step 1 — Install the Proxy

npm install -g @headlessops-ai/mcp

Step 2 — Configure Windsurf

In Windsurf Settings → MCP, use the stdio command instead of a URL:

{
  "mcpServers": {
    "headlessops": {
      "command": "headlessops-mcp",
      "args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
    }
  }
}

macOS Homebrew Node: Use /opt/homebrew/bin/headlessops-mcp as the command if Windsurf doesn't inherit your shell PATH.

Workspace Resolution

Create iterator/iterator.config.json in your project root to pin the workspace:

{ "workspaceId": "ws_abc123" }

To find your workspace ID, ask Cascade: "List my HeadlessOps workspaces"

Example Prompts

Once connected, try these in Windsurf's Cascade:

"List all my integrations in HeadlessOps"
"Show the last 10 runs of the invoice-processor integration"
"Create a new scheduled integration that syncs Airtable to HubSpot every night"
"The crm-sync integration failed — read the logs and fix the failing step"

Connect Windsurf