MCP Directory

How to add Winx Code Agent to Windsurf

Native Rust MCP server giving coding agents a PTY-backed shell, file IO, and tree-sitter code navigation. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 30★ · stdio · no auth

Windsurf config for Winx Code Agent

cargo install winx-code-agent
{
  "mcpServers": {
    "winx-code-agent": {
      "command": "winx-code-agent",
      "args": [],
      "env": {
        "RUST_LOG": "winx_code_agent=info"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Winx Code Agent config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Winx Code Agent's tools become available to Cascade.

Before you start

  • Rust 1.75+ (via `cargo install winx-code-agent`)
  • Linux, macOS, or WSL2
  • A real terminal (Winx spawns its own PTY)

What Winx Code Agent can do in Windsurf

Initialize

Boots the workspace, picks the mode (wcgw/architect/code_writer), and hands back a thread_id. Must be called first or everything else errors out. With no workspace path it spins up a scratch playground; passing task_id_to_resume reopens a saved project root.

BashCommand

Runs commands, polls long-running ones, and drives TUIs. Supports is_background, status_check, send_text, send_specials, send_ascii, allow_multi, plus screen (a point-in-time TUI frame, with diff:true for changed lines only) and wait_for_turn. Reports the real exit code parsed from the prompt marker.

ReadFiles

Reads one or many files with line numbers; append :10-40 (or :10- / :-40) to a path for a range. When the token budget is hit it tells you the exact line and file:N-M syntax to resume from instead of dropping the tail.

FileWriteOrEdit

Full overwrites or forgiving SEARCH/REPLACE blocks (with optional @start-end line anchors). Validates read coverage and freshness, reports fuzzy tolerances applied, runs a tree-sitter syntax check across 18+ languages, and returns a compact diff of what changed.

MultiFileEdit

Edits several files all-or-nothing: every file's edit is validated and computed in memory first, and only if all succeed is anything written, so a failed SEARCH in the last file leaves the earlier ones untouched.

UndoEdit

Reverts a file to its content before the last FileWriteOrEdit/MultiFileEdit this session (per-file, last ~10 edits kept in memory). Refused if the file changed on disk since the edit; a brand-new file's creation isn't undoable.

ContextSave

Dumps a task description plus file globs into a single text file with workspace context, active files, and git status/diff for clean handoff and task resumption.

ReadImage

Returns a native MCP image content block (not base64 text) so multimodal models actually see the image. Confined to the workspace and size-capped.

Security

A local stdio MCP server with full shell/file access inside the workspace - same blast radius as letting the model into your terminal. Secret redaction is on by default (disable with WINX_NO_REDACT=1) and the PTY process group is killed on teardown. Use `architect` (read-only) or `code_writer` (allowlist) mode, or WINX_SANDBOX=1 (Linux Landlock) for a tighter leash. The optional HTTP transport (`winx serve --http`) puts arbitrary shell/file access on the network: it requires a bearer token, refuses to start without one, binds to loopback by default, and has a DNS-rebinding guard - but anyone with the token gets a shell on your machine, so keep it behind an authenticated tunnel.

Winx Code Agent + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Winx Code Agent config there under the "mcpServers" key and restart the client.

Is Winx Code Agent safe to use with Windsurf?

A local stdio MCP server with full shell/file access inside the workspace - same blast radius as letting the model into your terminal. Secret redaction is on by default (disable with WINX_NO_REDACT=1) and the PTY process group is killed on teardown. Use `architect` (read-only) or `code_writer` (allowlist) mode, or WINX_SANDBOX=1 (Linux Landlock) for a tighter leash. The optional HTTP transport (`winx serve --http`) puts arbitrary shell/file access on the network: it requires a bearer token, refuses to start without one, binds to loopback by default, and has a DNS-rebinding guard - but anyone with the token gets a shell on your machine, so keep it behind an authenticated tunnel.

How do I install and run it?

Run `cargo install winx-code-agent` (needs Rust 1.75+); the binary lands in ~/.cargo/bin. Add it to your client with a `mcpServers` entry using command `winx-code-agent`, or for Claude Code run `claude mcp add winx -- winx-code-agent`. The first tool call must always be Initialize.

What are the three workspace modes?

wcgw gives full shell and file access; architect is read-only (no writes, most commands disabled); code_writer lets you allowlist commands and write globs, enforced with tree-sitter so it checks every command on a line including pipelines, subshells, and command substitution.

Can a cloud client like ChatGPT use it?

Yes. Run `winx serve --http --bind 127.0.0.1:8000 --token <secret>` to serve MCP over Streamable HTTP at /mcp. Every request must carry the token as an Authorization: Bearer header; the server refuses to start without a token. Put a tunnel (e.g. cloudflared) in front and allow its hostname through the DNS-rebinding guard.

View repo Full Winx Code Agent page