MCP Directory

How to add Winx Code Agent to Cursor

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

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the Winx Code Agent config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of Winx Code Agent's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the Winx Code Agent config there under the "mcpServers" key and restart the client.

Is Winx Code Agent safe to use with Cursor?

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