MCP VS Code

MCP VS Code embeds a self-hosted Code OSS/OpenVSCode workbench inside an MCP App. The model and the human operate the same workspace, open editors, diagnostics, commands, and terminal sessions in real time.

This is not remote control of a separately installed VS Code. The standalone distribution contains the editor server, Node.js runtime, MCP server, bridge extension, and web UI. Microsoft-hosted vscode.dev is not used because it disallows framing.

Project status: functional v0.1 implementation. Prerequisite-free releases target Windows x64, Linux x64, and Linux ARM64. Linux packages use verified upstream OpenVSCode archives; the Windows package is built in Windows CI from the pinned OpenVSCode source commit and exercised against the real workbench and bridge.

How it works

flowchart LR
    H["MCP host"] <-->|"stdio or Streamable HTTPS"| S["MCP VS Code server"]
    H --> A["Sandboxed MCP App view"]
    A -->|"nested iframe on an allowed frameDomain"| V["Bundled OpenVSCode workbench"]
    S --> W["Confined workspace"]
    S --> T["Shared PTYs"]
    V <-->|"authenticated local WebSocket"| B["Bridge extension"]
    B <--> S
    V --> W
    B --> T

The OpenVSCode process binds only to loopback. A gateway exposes it under a random, high-entropy path, avoiding third-party-cookie authentication inside the MCP sandbox. Remote MCP deployments must use TLS and bearer authentication.

Capabilities

• Self-hosted Code OSS workbench rendered inside the MCP App sandbox.
• Human editing, navigation, source control, commands, extensions, and terminal interaction.
• Live editor state, selections, dirty buffers, diagnostics, and file changes visible to MCP tools.
• Shared terminal sessions using the target-native PTY bundled with OpenVSCode, with a pipe-based fallback.
• Workspace confinement with traversal and symlink-escape protection.
• Conflict-safe file writes using SHA-256 version tokens.
• stdio and Streamable HTTP/HTTPS transports from the same executable.
• Generic vscode_execute_command escape hatch for every command registered in the live workbench.

The server currently exposes 27 tools across these groups:

Group	Tools
App/session	vscode_open, workspace_status
Files	fs_list, fs_read, fs_write, fs_delete, fs_move, fs_search
Editor	editor_open, editor_state, editor_set_selection, editor_apply_edits
Language services	diagnostics_get
Commands	vscode_list_commands, vscode_execute_command
Extensions	extensions_list, extensions_install, extensions_uninstall
Terminals	terminal_create, terminal_list, terminal_read, terminal_write, terminal_resize, terminal_kill
Git	git_status, git_diff, git_run

Destructive and open-world tools are annotated accordingly so compatible MCP hosts can apply their approval policy.

Install a standalone release

Download and extract the release archive for your platform.

Windows x64:

.\bin\mcp-vscode.cmd --stdio --workspace C:\path\to\repository

Linux x64 or ARM64:

./bin/mcp-vscode --stdio --workspace /absolute/path/to/repository

The archive contains its own Node.js and OpenVSCode runtimes. It does not require VS Code, Node.js, Docker, or a system-wide package installation.

Run from npm on Windows

Windows x64 users with Node.js 22 or newer can start the bundled stdio server directly through npm:

npx -y @mario.andreschak/mcp-vscode@0.1.4 --stdio --workspace "C:\path\to\repository"

For MCP clients that configure the workspace through an environment variable:

{
  "mcpServers": {
    "vscode": {
      "command": "npx",
      "args": ["-y", "@mario.andreschak/mcp-vscode@0.1.4", "--stdio"],
      "env": {
        "MCP_VSCODE_WORKSPACE": "C:\\path\\to\\repository"
      }
    }
  }
}

The npm package is intentionally restricted to Windows x64. Linux x64 and ARM64 users should use the standalone release archives above.

Example MCP client configuration:

{
  "mcpServers": {
    "vscode": {
      "command": "/opt/mcp-vscode/bin/mcp-vscode",
      "args": ["--stdio", "--workspace", "/work/my-repository"]
    }
  }
}

Calling vscode_open renders the workbench. The app requests fullscreen mode when the user selects Fullscreen.

Run over HTTPS

./bin/mcp-vscode \
  --http \
  --https \
  --host 0.0.0.0 \
  --port 8443 \
  --workspace /work/my-repository \
  --public-url https://editor.example.com:8443 \
  --auth-token "$MCP_VSCODE_TOKEN" \
  --cert /run/secrets/tls.crt \
  --key /run/secrets/tls.key

The MCP endpoint is https://editor.example.com:8443/mcp. Binding beyond loopback is rejected unless both TLS and a bearer token are configured.

MCP host requirements

The host must support the stable MCP Apps extension io.modelcontextprotocol/ui and:

• text/html;profile=mcp-app resources;
• the declared frameDomains, connectDomains, and resourceDomains;
• nested iframe scripts, workers, WebSockets, and same-origin behavior;
• a sufficiently large inline container or fullscreen display mode.

If a host blocks the OpenVSCode frame, the app displays the exact runtime or policy error instead of silently opening an external browser tab.

Build from source

Requirements for development only: Node.js 22+.

npm ci
npm run check

Useful commands:

npm run dev -- --http --port 3001 --workspace . --ide-url http://127.0.0.1:3999
npm run dev:mock-ide -- --port 3999
npm run runtime:fetch -- linux-x64
npm run runtime:build -- win32-x64
npm run package:standalone -- linux-x64
npm run package:standalone -- win32-x64

The runtime fetcher pins OpenVSCode 1.109.5 and verifies upstream Linux SHA-256 digests before extraction. Native Windows builds pin and verify upstream commit 4ffe2270acdf711bbefecc3e8c79f4b3631640e5, then invoke Code OSS's vscode-reh-web-win32-x64 build target. Building that runtime locally requires Windows x64, Git, Node.js 22.21.1 or newer, and the Visual Studio 2022 C++ build tools with Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre. Release archives contain the resulting runtime and do not require those development tools. Runtime and standalone output directories are ignored by Git.

Security model

• Every file path is resolved beneath one configured workspace root. Existing symlinks are canonicalized before access.
• The workspace root cannot be deleted through MCP tools.
• OpenVSCode listens on loopback and is exposed through an unguessable per-process path.
• The bridge uses a separate 256-bit token and accepts one active bridge connection.
• Remote listeners require HTTPS and bearer authentication.
• Git hooks are disabled for git_run; arbitrary VS Code commands and shell input remain powerful and should require host approval.
• Unsaved text documents up to 2 MB are mirrored into the MCP-visible overlay. Larger dirty documents remain available through editor commands but are not copied on every keystroke.

See SECURITY.md for reporting and deployment guidance.

Upstream and trademarks

OpenVSCode Server and Code OSS are MIT-licensed upstream projects. MCP VS Code is independent and is not affiliated with or endorsed by Microsoft or Gitpod. “Visual Studio Code” and “VS Code” are trademarks of Microsoft Corporation.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.