Windsurf integration

Install and wire mog skills, rules, and MCP servers into Windsurf with automatic configuration.

mog has first-class support for Windsurf (by Codeium). The CLI auto-detects Windsurf projects, installs skill packages to .windsurf/skills/, and writes MCP server config to Windsurf's global config file.

How auto-detection works

When you run mog install in a project directory, the CLI looks for a .windsurf/ directory. If it finds one, it sets the target to windsurf and uses Windsurf-specific install paths. You can always override with --target windsurf.

Installing skills

Skills are SKILL.md packages that teach Windsurf's Cascade AI specific capabilities.

mog install acme/react-testing-skill

This downloads the package, verifies its SHA-256 hash, and extracts it to:

.windsurf/skills/react-testing-skill/
  SKILL.md
  README.md

Installing MCP servers

MCP server packages are configured by writing to Windsurf's global MCP config file — unlike other targets, this is not project-scoped.

mog install acme/github-mcp-server

The CLI prompts for any required environment variables and writes the config:

{
  "mcpServers": {
    "acme-github-mcp-server": {
      "command": "npx",
      "args": ["-y", "@acme/github-mcp-server@1.0.0"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

If mcp_config.json already has other servers configured, mog merges the new entry without overwriting existing ones.

Global scope

Windsurf's MCP config is global (~/.codeium/windsurf/mcp_config.json), meaning MCP servers installed via mog are available across all your Windsurf projects. This differs from Cursor and Claude Code where MCP config is per-project.

Accessing MCP settings in Windsurf

You can also open the MCP config from within Windsurf:

Command Palette: Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), then search "Windsurf: Configure MCP Servers"
Cascade toolbar: Click the hammer icon and select Configure
Settings: Open Windsurf Settings and search for "MCP"

Passing env vars non-interactively

For CI or agent-driven installs, pass environment variables with --env:

mog install acme/github-mcp-server --env GITHUB_TOKEN=ghp_xxx

Supported transports

Windsurf supports stdio, Streamable HTTP, and SSE transports for MCP servers. For HTTP servers, use serverUrl or url fields instead of command and args.

Tool limits

Cascade has a limit of 100 total MCP tools active at any given time. If you have many MCP servers installed, you can toggle individual server tools on or off through Windsurf's MCP settings page.

Restart Windsurf after installing an MCP server for it to be discovered.

Project health check

Run mog doctor to verify your Windsurf project is set up correctly:

mog doctor

This checks:

CLI authentication status
Lockfile integrity (mog.lock.json)
Installed packages match the lockfile (version and SHA-256)
MCP server config validity

Listing installed packages

mog ls

2 installed packages

acme/react-testing-skill@1.2.0  windsurf
  .windsurf/skills/react-testing-skill/
  Installed: 1/15/2026

acme/github-mcp-server@1.0.0  windsurf (mcp)
  ~/.codeium/windsurf/mcp_config.json
  Installed: 1/16/2026

Updating packages

mog update --dry-run
mog update

Updates respect semver: by default only patch and minor versions are applied. The lockfile is updated and the old files are replaced.

Uninstalling

mog uninstall acme/react-testing-skill

For skills, this removes the extracted files from .windsurf/skills/ and the lockfile entry.

For MCP servers, this removes the mcpServers entry from ~/.codeium/windsurf/mcp_config.json.

File layout summary

After installing skills and MCP servers:

my-project/
  .windsurf/
    skills/
      react-testing-skill/
        SKILL.md
        README.md
      another-skill/
        SKILL.md
  mog.lock.json                              # Lockfile (commit to version control)

~/.codeium/windsurf/
  mcp_config.json                            # Global MCP server configs

Tips

Commit mog.lock.json to version control so teammates get the same package versions.
MCP config is global — be aware that installing or uninstalling MCP servers affects all Windsurf projects on your machine.
Windsurf has a built-in MCP Marketplace accessible from the Cascade panel. mog complements this with its own cross-platform marketplace and CLI-driven workflow.
Use mog explain <vendor>/<package> to preview a package's metadata, install path, and target compatibility before installing.
Use mog install --preflight to see exactly what would happen without making changes.