Windsurf MCP Sidecar Guide

Connect AIWG to Windsurf Cascade AI as an MCP sidecar for structured workflow access.

This is not a standard provider deployment. Windsurf is an IDE-integrated AI assistant that cannot be spawned from the CLI. The MCP sidecar provides structured AIWG tool access from within Windsurf's Cascade agent. The architecture is `Windsurf Cascade AI → MCP → AIWG Server`. Windsurf supports stdio, Streamable HTTP, and SSE transports for MCP connections, with a 100-tool limit across all connected servers.

Architecture

Windsurf Cascade AI (host)
  ├── Cascade conversation and workflows
  ├── AGENTS.md (aggregated agent definitions)
  ├── .windsurf/ (skills, rules, workflows)
  └── MCP connection
        └── AIWG MCP Server (sidecar)
              └── .aiwg/ artifacts, workflows, templates

Windsurf owns: Cascade conversation context, AGENTS.md aggregation, `.windsurf/` directory, workflow invocation.

AIWG owns: workflow execution, artifact output in `.aiwg/`, template rendering, agent role definitions.

MCP is the seam. Windsurf already receives AIWG agent and workflow definitions via `aiwg use sdlc --provider windsurf`. The MCP sidecar adds structured, callable AIWG tooling on top of that foundation — without replacing it.

Prerequisites

Windsurf installed and running (windsurf.ai)
AIWG installed: `npm install -g aiwg`
A project with AIWG deployed for Windsurf:

cd /path/to/your/project
aiwg use sdlc --provider windsurf

If you have not done the base deployment yet, complete the Windsurf Quick Start first, then return here.

Install MCP Configuration

Run the AIWG install command to write the MCP configuration for Windsurf:

aiwg mcp install windsurf

This writes (or updates) `~/.codeium/windsurf/mcp_config.json` with the AIWG server entry.

Verify the config was written:

cat ~/.codeium/windsurf/mcp_config.json

You should see:

{
  "mcpServers": {
    "aiwg": {
      "command": "aiwg",
      "args": ["mcp", "serve"]
    }
  }
}

After writing the config, restart Windsurf to pick up the new MCP server.

Configure Tool Whitelist

The default config connects to the full AIWG MCP surface. Restrict to the five core tools to keep Cascade's context budget manageable:

Edit `~/.codeium/windsurf/mcp_config.json`:

{
  "mcpServers": {
    "aiwg": {
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "tools": {
        "include": [
          "discover",
          "command-run",
          "artifact-read",
          "artifact-write",
          "template-render",
          "agent-list"
        ],
        "prompts": false,
        "resources": false
      }
    }
  }
}

Why this whitelist: Each MCP server exposes its tool schemas into the Cascade context window before any tool is called. The lean whitelist keeps discovery, CLI dispatch, artifact IO, templates, and agents available without enabling every opt-in subsystem. See the Context Budget section for the full breakdown.

A ready-to-use minimal config template is available at `agentic/code/frameworks/sdlc-complete/templates/windsurf/windsurf-mcp-minimal.json`.

Verify the Connection

After restarting Windsurf, ask Cascade to confirm the tools are available:

What AIWG MCP tools are available?

Cascade should list the lean whitelisted tools, including `discover`, `command-run`, `artifact-read`, `artifact-write`, `template-render`, and `agent-list`.

Verify AIWG MCP server runs independently:

aiwg mcp info    # Show capabilities
aiwg version     # Confirm CLI is in PATH

If Cascade cannot see the tools, check that `aiwg` is accessible from the PATH that Windsurf uses when launching processes.

Run Your First Workflow

Ask Cascade to create a structured artifact that routes through the AIWG MCP server:

Create an architecture decision record for choosing PostgreSQL over MongoDB
for our user service. Save it as a persistent AIWG artifact.

What should happen:

1. Cascade recognizes this as a structured artifact request 2. Cascade calls `command-run`, `template-render`, or `artifact-write` via MCP 3. AIWG creates the artifact in `.aiwg/architecture/` 4. Cascade reports the result

Verify the artifact was written:

ls .aiwg/architecture/

You should see the new ADR file.

Context Budget

Understanding the token footprint helps you configure the whitelist for your needs.

With lean whitelist (recommended)

Component	Tokens
Cascade system context	~2,000
AGENTS.md (aggregated agents)	~3,500
AIWG MCP schema (lean tools)	bounded
Total overhead	~8,500
Available for work (128K context)	~119,500 (93%)

Without whitelist (full surface)

Component	Tokens
Cascade system context	~2,000
AGENTS.md (aggregated agents)	~3,500
AIWG MCP schema (core + opt-in toolsets)	larger
Total overhead	~17,500
Available for work (128K context)	~110,500 (86%)

Windsurf has a large default context window, so the absolute impact is lower than on memory-constrained local models. The whitelist still matters for response latency: Cascade must process all schema tokens on every tool-using turn.

Advanced — Enable Prompts

After the basic integration is stable, you can enable AIWG prompt exposure for richer workflow access.

Update `~/.codeium/windsurf/mcp_config.json`:

{
  "mcpServers": {
    "aiwg": {
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "tools": {
        "include": [
          "discover",
          "command-run",
          "artifact-read",
          "artifact-write",
          "template-render",
          "agent-list"
        ],
        "prompts": true,
        "resources": false
      }
    }
  }
}

This adds AIWG workflow prompts as callable templates from within Cascade. Only enable after the base integration in the previous sections is working reliably.

A ready-to-use full config template is available at `agentic/code/frameworks/sdlc-complete/templates/windsurf/windsurf-mcp-full.json`.

Validation Checklist

Run these checks to confirm the integration is working:

Check	Action	Expected
Connectivity	Ask "What AIWG tools are available?"	Lean tools listed
Routing (direct)	Ask a one-off question	Cascade answers directly (no MCP call)
Routing (artifact)	Ask for a requirements document	Routes to AIWG via MCP
Artifact write	Check `.aiwg/` after workflow	New artifact file exists
Artifact read	Ask Cascade to read an existing artifact	Uses `artifact-read`
Failure mode	Run `aiwg mcp serve` in isolation, confirm it starts	No errors

Troubleshooting

AIWG tools not visible in Cascade:

Verify `aiwg mcp serve` runs successfully on its own
Confirm `~/.codeium/windsurf/mcp_config.json` is valid JSON (use `jq . ~/.codeium/windsurf/mcp_config.json`)
Ensure `aiwg` is in your PATH (check `which aiwg`)
Restart Windsurf after any config change

Artifacts not appearing in `.aiwg/`:

Confirm AIWG is initialized in the project (`aiwg use sdlc --provider windsurf`)
Check that `artifact-write` is in the tool whitelist
Verify Windsurf's working directory matches the project root

Context growing too fast:

Confirm `prompts: false` and `resources: false` in the MCP config
Keep the whitelist lean unless you have a specific reason to add more tools or toolsets

Config location not found:

The config path is `~/.codeium/windsurf/mcp_config.json`
Create the directory if it does not exist: `mkdir -p ~/.codeium/windsurf`
Re-run `aiwg mcp install windsurf` after creating the directory

Windsurf Quick Start — base provider deployment (prerequisite)
Hermes MCP Sidecar Guide — reference architecture this guide follows
AIWG MCP server reference
Windsurf Documentation

Windsurf MCP Sidecar Guide

Windsurf MCP Sidecar Guide

Architecture

Prerequisites

Install MCP Configuration

Configure Tool Whitelist

Verify the Connection

Run Your First Workflow

Context Budget

With lean whitelist (recommended)

Without whitelist (full surface)

Advanced — Enable Prompts

Validation Checklist

Troubleshooting

Related Resources