Windsurf

Editor

Cognition

Agentic AI code editor built around the Cascade agent, created by Codeium and now maintained by Cognition as Devin Desktop.

Website Docs

MCP

Supported

Configure MCP servers for Cascade in mcp_config.json under the mcpServers key, or install from the built-in MCP Marketplace. Supports stdio, Streamable HTTP, and SSE with OAuth for each transport.

Verified 2026-07-12Docs

Transportsstdiohttpsse

Authoauthheaders

Config files

Path	Scope	Format	Key
`~/.codeium/windsurf/mcp_config.json` Also editable via the MCP Marketplace / MCP Servers settings UI.	Global	json	mcpServers

Fields

Field	Type	Description
`command`	string	Command to start a local (stdio) server, e.g. npx, docker, node.
`args`	string[]	Arguments passed to the command.
`env`	record<string, string>	Environment variables for the server. Supports ${env:...} and ${file:...} interpolation.
`serverUrl`	string	Endpoint URL for a remote (HTTP/SSE) server. url is also accepted.
`headers`	record<string, string>	HTTP headers for a remote server (e.g. API keys, Authorization). Supports interpolation.
`disabledTools`	string[]	Tools to disable for this server (excluded from enterprise whitelist matching).

Capabilities

ToolsSupported

PromptsSupported

ResourcesSupported

Examples

Local stdio server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

Remote HTTP server with header interpolation

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

•Remote servers use a serverUrl (or url) field instead of command/args.
•Cascade has a limit of 100 total MCP tools enabled at any given time; individual tools can be toggled per server.
•command, args, env, serverUrl, url, and headers support ${env:VAR_NAME} and ${file:/path/to/file} interpolation to avoid hardcoding secrets.
•One-click installs via windsurf://windsurf-mcp-registry deeplinks; teams can whitelist servers or point at custom MCP registries (enterprise).

Skills

Supported

Folder-based SKILL.md skills (Agent Skills standard) that bundle instructions with supporting files. Cascade sees only name and description until it invokes the skill (progressive disclosure).

Verified 2026-07-12Docs

Invokeautomatic@skill-name

Config files

Path	Scope	Format	Key
`.windsurf/skills/<name>/SKILL.md` Workspace skills, committed with the repo.	Project	markdown	—
`~/.codeium/windsurf/skills/<name>/SKILL.md` Global skills, available in all workspaces. Not committed.	Global	markdown	—
`/etc/windsurf/skills/<name>/SKILL.md` System skills deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/skills/, Windows: C:\ProgramData\Windsurf\skills\). Read-only for end users.	Enterprise	markdown	—

Fields

Field	Type	Description
`name`*	string	Unique skill identifier (lowercase letters, numbers, hyphens). Displayed in the UI and used for @-mentions.
`description`*	string	Brief explanation shown to the model so Cascade can decide when to invoke the skill.

Examples

Skill with frontmatter

---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---

## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables

## Deployment Steps
Follow these steps to deploy safely...

•Supporting files (scripts, templates, checklists) placed next to SKILL.md become available when the skill is invoked.
•For cross-agent compatibility, skills are also discovered in .agents/skills/ and ~/.agents/skills/; with Claude Code config reading enabled, .claude/skills/ and ~/.claude/skills/ are scanned too.
•Skills can also be created from the Cascade Customizations UI (+ Workspace / + Global).

Rules

Supported

User-defined rules at global, workspace, and system level, with per-rule activation modes (always_on, glob, model_decision, manual). AGENTS.md files are fed into the same rules engine with location-based scoping.

Verified 2026-07-12Docs

Invoke@rule-name

Config files

Path	Scope	Format	Key
`.windsurf/rules/.md` One file per rule with frontmatter activation mode. .devin/rules/.md is preferred in newer builds.	Project	markdown	—
`.windsurfrules` Legacy single-file workspace rules at the repo root; still read.	Project	markdown	—
`AGENTS.md` Root and any subdirectory. Root = always-on, subdirectory = auto-glob for that directory. No frontmatter.	Project	markdown	—
`~/.codeium/windsurf/memories/global_rules.md` Single always-on file applied across all workspaces. Max 6,000 characters.	Global	markdown	—
`/etc/windsurf/rules/*.md` System rules deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/rules/, Windows: C:\ProgramData\Windsurf\rules\). Merged with user rules, read-only.	Enterprise	markdown	—

Fields

Field	Type	Description
`trigger`	string	Activation mode declared in the rule's frontmatter.
`description`	string	Shown in the system prompt for model_decision rules; Cascade reads the full rule when it decides the description is relevant.
`globs`	string	Glob pattern(s) for glob-triggered rules (e.g. */.test.ts); applied when Cascade reads or edits matching files.

Examples

Glob-scoped workspace rule

---
trigger: glob
globs: **/*.test.ts
---

All test files must use `describe`/`it` blocks and mock external API calls.

•Newer builds prefer .devin/rules/*.md over .windsurf/rules/*.md; both are read (.devin takes precedence).
•Rules are discovered in the workspace, its subdirectories, and parent directories up to the git root.
•Workspace rule files are limited to 12,000 characters each; the global rules file to 6,000 characters.
•Root-level AGENTS.md is always-on; AGENTS.md in a subdirectory becomes a glob rule for <directory>/**. agents.md (lowercase) also works.
•Cascade also auto-generates Memories (stored locally in ~/.codeium/windsurf/memories/) that are retrieved when relevant; these are separate from user-defined rules.

Hooks

Supported

Cascade Hooks run shell commands at key points in the agent workflow, configured in hooks.json at system, user, and workspace level (merged, executed system -> user -> workspace). Hooks receive event JSON on stdin; pre-hooks can block the action by exiting with code 2.

Verified 2026-07-12Docs

Eventspre_read_codepost_read_codepre_write_codepost_write_codepre_run_commandpost_run_commandpre_mcp_tool_usepost_mcp_tool_usepre_user_promptpost_cascade_responsepost_cascade_response_with_transcriptpost_setup_worktree

Config files

Path	Scope	Format	Key
`.windsurf/hooks.json` Workspace hooks, version-controlled with the repo.	Project	json	hooks
`~/.codeium/windsurf/hooks.json` User-level hooks (JetBrains plugin reads ~/.codeium/hooks.json).	Global	json	hooks
`/etc/windsurf/hooks.json` System hooks deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/hooks.json, Windows: C:\ProgramData\Windsurf\hooks.json).	Enterprise	json	hooks

Fields

Field	Type	Description
`command`	string	Shell command to run on macOS/Linux (via bash -c). At least one of command or powershell is required.
`powershell`	string	Command to run on Windows (via powershell -Command). Falls back to command when omitted.
`show_output`	boolean	Whether to display the hook's stdout/stderr in the Cascade UI.
`working_directory`	string	Directory to run the command from. Defaults to the workspace root; ~ expansion is not supported.

Examples

Block dangerous commands and format after edits

{
  "hooks": {
    "pre_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/block_dangerous_commands.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "bash /Users/yourname/hooks/format_code.sh",
        "show_output": false
      }
    ]
  }
}

•Exit code 0 = proceed; exit code 2 = blocking error (pre-hooks only); other codes = non-blocking error.
•Only pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, and pre_mcp_tool_use can block actions.
•Every hook receives common JSON fields: agent_action_name, trajectory_id, execution_id, timestamp, model_name, and event-specific tool_info.
•post_cascade_response_with_transcript writes a full JSONL conversation transcript to ~/.windsurf/transcripts/{trajectory_id}.jsonl.
•Enterprise teams can also distribute hooks via the cloud dashboard (Team Settings > Cascade Hooks); cloud hooks load before system, user, and workspace hooks.

Commands

Supported

Workflows are markdown prompt templates invoked manually with /workflow-name slash commands. Cascade processes the steps sequentially; workflows can call other workflows.

Verified 2026-07-12Docs

Invoke/workflow-name

Config files

Path	Scope	Format	Key
`.windsurf/workflows/*.md` Workspace workflows, committed with the repo.	Project	markdown	—
`~/.codeium/windsurf/global_workflows/*.md` Global workflows available in every workspace. Not committed.	Global	markdown	—
`/etc/windsurf/workflows/*.md` System workflows deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/workflows/, Windows: C:\ProgramData\Windsurf\workflows\). Highest precedence, read-only.	Enterprise	markdown	—

Examples

Workflow to address PR comments

1. Check out the PR branch: `gh pr checkout [id]`
2. Get comments on the PR via `gh api`
3. For EACH comment: analyze the file and line range, make the change
   if it is clear, otherwise ask for clarification.
4. After all comments are processed, summarize what you did and which
   comments need the USER's attention.

•Manual-only: Cascade never invokes a workflow automatically (use a Skill for model-invoked procedures).
•Workflow files are limited to 12,000 characters each.
•Workflows are discovered in the workspace, its subdirectories, and parent directories up to the git root.
•Precedence when names collide: system > workspace > global > built-in (e.g. /plan).
•Workflows contain a title, description, and a series of steps; a workflow can include instructions like 'Call /other-workflow'.

Settings

Partial

Agent-relevant settings live in the in-app settings UI (Cascade gitignore access, diff zones, terminal allow/deny lists, marketplace URL); there is no documented user-editable settings file for agent behavior. Enterprises can enforce settings centrally via OS-level policies.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`/etc/windsurf/policies/policy.json` Linux JSON policy file deployed by IT. Windows uses registry-based group policy, macOS uses configuration profiles.	Enterprise	json	—

Fields

Field	Type	Description
`AllowedExtensions`	string (JSON)	Allowlist of permitted extension publishers, e.g. {"windsurf": true, "github": true}.
`UpdateMode`	string	Controls how the editor updates (e.g. manual).
`EnableTelemetry`	boolean	Enable or disable telemetry.

Examples

Linux policy file

{
  "AllowedExtensions": "{\"publisher1\": true, \"publisher2\": true}",
  "UpdateMode": "manual"
}

•User settings are managed via the settings UI (top-right dropdown or Command Palette > Open User Settings) rather than a documented config file.
•Enterprise policy values override settings configured at any level (default, user, workspace).
•Windows policies are read from the registry at Software\Policies\Windsurf\{ProductName}; macOS uses .mobileconfig configuration profiles.
•Documented policies include AllowedExtensions (JSON allowlist of extension publishers), UpdateMode, EnableTelemetry, and EnableFeedback.