How to add PiloTY to Windsurf

Persistent, interactive PTY terminal for AI agents over MCP — SSH, REPLs, password prompts, long-running jobs. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf config for PiloTY

codex mcp add piloty -- uvx --from git+https://github.com/yiwenlu66/PiloTY.git piloty

{
  "mcpServers": {
    "piloty": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yiwenlu66/PiloTY.git",
        "piloty"
      ]
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

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

Before you start

uv / uvx (Astral) to launch the server via `uvx`, or a local clone run with `uv --directory`
An MCP client that launches servers over stdio (e.g. Codex CLI, Claude)
Python (server is implemented in Python)

What PiloTY can do in Windsurf

send_line

Submit a newline-terminated command to the terminal session (drain-based).

send_text

Send raw bytes to the terminal without an appended newline (drain-based).

send_control

Send a control character (e.g. interrupt) to the foreground process (drain-based).

send_signal

Send a signal to the session's process (drain-based).

send_password

Enter a secret for a password prompt; suppresses transcript logging and terminal echo for that send (drain-based).

wait_for_output

Wait for new PTY output for a wall-clock budget; can return partial output with outcome=deadline_exceeded if output started but never went quiet.

wait_for_regex

Wait for content matching a regex; first checks already-rendered scrollback, then waits on new PTY bytes.

wait_for_shell_prompt

Wait for the shell prompt to return (e.g. after `ssh` or other login flows), consuming and returning the PTY output it waits on.

Security

PiloTY exposes unrestricted terminal access — treat it like giving the agent your keyboard. `send_password()` suppresses transcript logging and terminal echo for that send, but does not prevent other prompts or programs from echoing secrets later. Each server instance writes session logs (raw PTY bytes, inputs, captured output) under `~/.piloty/`, with server logs defaulting to `/tmp/piloty.log`.

PiloTY + Windsurf FAQ

Where is the Windsurf config file?

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

Is PiloTY safe to use with Windsurf?

How does state persist between tool calls?

Each session is one real interactive terminal addressed by a `session_id` string. Reusing the same id keeps cwd, environment variables, the foreground process, remote SSH connections, and REPL/debugger state alive. Since MCP has no standard 'client cwd' field, the first step is always to create a session with an explicit working directory.

What is the difference between `outcome` and `terminal_state`?

`outcome` is the call result (success, deadline_exceeded, eof, error, invalid_session, terminated). `terminal_state` is a best-effort classification of the rendered terminal after the call (running, ready, password, confirm, repl, editor, pager, unknown). Terminal-state detection can be wrong, especially for custom prompts and cursor-heavy TUIs.

Is it safe to give an agent this kind of access?

PiloTY exposes unrestricted terminal access — treat it like giving the agent your keyboard. `send_password` suppresses logging/echo for that send but cannot prevent other programs from echoing secrets later. Session transcripts are written under `~/.piloty/`.

View repo Full PiloTY page