MCP VS Code

MCP VS Code runs a self-hosted Code OSS/OpenVSCode workbench beside an MCP server so the human and the model operate the same workspace, open editors, diagnostics, commands, extensions, and terminal sessions. This is not remote control of a separately installed desktop VS Code. Supported distributions carry their own OpenVSCode runtime and bridge extension. Microsoft-hosted vscode.dev is not used because it disallows framing.

The caveman picture

There are four pieces:

1. The MCP host—for example FLUJO or Claude Desktop—owns the outer sandbox and its security policy.
2. The small MCP App document asks the host for permission to reach and, in default mode, frame the workbench origin.
3. The mcp-vscode gateway exposes only the routes needed to reach the private runtime.
4. The OpenVSCode process runs on the MCP server machine, binds to loopback, opens the configured workspace, and connects its bridge extension back to the MCP server.

flowchart LR
    H["MCP host"] <-->|"stdio or Streamable HTTPS"| S["mcp-vscode server"]
    H --> A["sandboxed MCP App"]

    A -->|"default: allowed frameDomains"| I["OpenVSCode iframe"]
    A <-->|"opt-in: authenticated /stream WebSocket"| C["pixel canvas"]
    A -->|"honest fallback: openLink"| X["separate browser tab"]

    I --> G["browser-reachable gateway origin"]
    X --> G
    C <-->|"JPEG frames + input"| B["server-side system Chromium"]
    B --> O["loopback OpenVSCode"]
    G --> O
    O <-->|"authenticated /bridge WebSocket"| S
    S --> W["confined workspace and PTYs"]
    O --> W

The default iframe and browser-tab paths deliver OpenVSCode directly. Experimental streaming launches an existing Edge, Chrome, or Chromium on the server, points it at that same OpenVSCode runtime, and transports its pixels and user input. The canvas is a remote display, not another editor implementation.

Rendering modes

probing is a temporary UI state, not a renderer.

Default behavior: iframe or browser

With no render-mode environment variable, the App:

1. waits for the bundled OpenVSCode runtime;
2. compares the workbench origin with the effective frameDomains reported by the host when that information is available;
3. skips iframe navigation immediately when the host explicitly denied the origin;
4. otherwise navigates the iframe and waits for the injected mcp-vscode:workbench-alive message;
5. commits embedded only after that positive signal; or
6. shows the browser card with the exact policy, network, or runtime reason.

A CSP-blocked iframe can emit neither a useful load nor error event, so a plain iframe event is not treated as success. The liveness timeout prevents a permanent blank view.

An MCP server's CSP declaration is a permission request, not a way to overrule the host. A host may approve it, restrict it, or deny it. CORS headers on mcp-vscode cannot repair a frame-src decision made by the outer host.

Experimental streaming

Set:

MCP_VSCODE_RENDER_MODE=stream

Streaming deliberately replaces the iframe decision for that process; it is not an automatic fallback. If streaming cannot start, the App reports the failure and moves to the honest browser option rather than silently selecting a different editor.

The server:

• discovers an existing Microsoft Edge, Google Chrome, or Chromium installation, or uses MCP_VSCODE_STREAM_BROWSER;
• launches it headlessly with a dedicated ephemeral user-data directory;
• when the POSIX server runs as root with Chromium's sandbox enabled, reads the fixed node account from /etc/passwd, transfers ownership of that private profile, and drops only the Chromium child to its non-zero uid/gid;
• points Chromium's working directory, HOME, TMPDIR, and XDG directories into that same ephemeral profile instead of inheriting the server account's paths;
• binds its Chrome DevTools Protocol listener to 127.0.0.1 only;
• navigates to a server-selected internal OpenVSCode URL—the App cannot navigate Chromium or issue arbitrary DevTools commands;
• emits JPEG screencast frames at up to 12 frames per second;
• accepts bounded resize, pointer, wheel, keyboard, and text-input messages; and
• permits one active viewer.

The /stream WebSocket uses its own random 256-bit bearer token. Both the tokenized stream URL and the high-entropy /ide/<key> URL are excluded from model-visible tool text and structuredContent; they are delivered to the MCP App through tool-result _meta only. Logs do not contain the stream token.

Streaming is useful when a host grants connectDomains but refuses frameDomains, which is the behavior observed with locally configured Claude Desktop stdio connectors in the test documented in the upstream report draft.

Streaming remains experimental:

• JPEG frames consume more CPU and bandwidth and feel less immediate than a direct iframe.
• There is no audio and only one viewer.
• Basic mouse, keyboard, wheel, and paste input work; clipboard copy and complex IME composition are incomplete.
• A system Chromium-family browser is an additional prerequisite. The project does not download or bundle one for this mode.
• The gateway WebSocket must be browser-reachable. Streaming does not make a private Fly Machine port magically reachable.

Failure means failure

All three displayed outcomes refer to the real OpenVSCode runtime. If that runtime is missing or failed, there is no editor UI to show. File, Git, and terminal MCP tools may still operate where applicable, but editor/diagnostics/command/extension tools that require the live bridge fail explicitly.

There is no special macOS editor fallback: without an OpenVSCode Server runtime, neither embedding, streaming, nor the external-browser view can provide the workbench.

Configuration

User-facing environment variables

FLUJO-managed hosted children may also receive FLUJO_MCP_APP_RUNTIME_REGISTER_URL and FLUJO_MCP_APP_RUNTIME_REGISTER_TOKEN. Those are short-lived internal broker capabilities, not user settings. mcp-vscode proves possession, registers an allowlisted route manifest, clears both variables before OpenVSCode starts, and never exposes the bearer to the workbench.

Claude Desktop example

Default mode honestly falls back to a browser when the tested Claude Desktop host declines the local loopback frameDomains request:

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

To test genuine inline streaming instead:

{
  "mcpServers": {
    "vscode": {
      "command": "npx",
      "args": ["-y", "@mario.andreschak/mcp-vscode@0.2.4", "--stdio"],
      "env": {
        "MCP_VSCODE_WORKSPACE": "C:\\path\\to\\repository",
        "MCP_VSCODE_RENDER_MODE": "stream",
        "MCP_VSCODE_STREAM_BROWSER": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
      }
    }
  }
}

The browser-path override is optional when discovery finds an installed browser. Host behavior changes over time; re-run the manual matrix against the exact Claude Desktop version rather than treating the current observation as permanent.

FLUJO and Fly.io deployment

A user can visit one human-facing site such as try.flujo.com.co, while the browser uses additional security origins behind the scenes. A sandboxed MCP App and its nested workbench cannot safely be collapsed into one literal browser origin merely to make deployment look simpler.

For a FLUJO-managed stdio child, the runtime-broker handshake solves the private-port problem: