Named Pipe Listener

Source of Truth: docs/ARCHITECTURE.md
Status: Canonical repo cleanup aligned to the current architecture as of 2026-05-16. Bracket-style tokens are intentional BlogEngine/GwnWikiExtension tokens.

Understanding a Named Pipe Listener

In the VS MCP Bridge architecture, the Visual Studio side of the system does not wait for natural-language prompts from an AI tool. It waits for structured bridge requests.

That waiting point is the named-pipe side of the bridge.

A named pipe is a local inter-process communication channel provided by the operating system. One process creates the pipe and waits for a connection. Another process connects and exchanges messages. No public network port is required.

In this project, the named-pipe boundary exists because the MCP server and the Visual Studio extension have different jobs. The MCP server speaks MCP over stdio to the AI client. The VSIX runs inside Visual Studio and owns Visual Studio APIs, editor state, proposal application, and host-specific behavior.

The Short Version

The current VS-backed tool path is:

AI client
  -> MCP over stdio
VsMcpBridge.McpServer
  -> PipeClient
local named pipe: VsMcpBridge
  -> PipeServer in the VSIX
VsService
  -> Visual Studio APIs / editor state

The important boundary is simple: stdio gets the request into the local MCP server, and the named pipe gets Visual Studio-backed work into the VSIX.

Why the VSIX Side Is Isolated from stdio

The VSIX runs inside Visual Studio. It can access DTE, editor state, solution state, the Error List, and the proposal-approval UI. The MCP server does not run inside Visual Studio and should not pretend to be the IDE host.

Keeping stdio out of the VSIX gives the bridge a cleaner architecture:

• The AI client talks MCP to a local server process.
• The MCP server keeps stdout reserved for MCP protocol responses.
• The VSIX owns Visual Studio-specific work and Visual Studio privileges.
• The named pipe provides a local-only bridge between those two processes.

This is why the named pipe is not just an implementation detail. It is the local host boundary between the AI-facing process and the IDE-facing process.

PipeClient and PipeServer Responsibilities

The named-pipe layer has two sides.

PipeClient lives in the MCP server process. For VS-backed tools, it connects to the local pipe name, writes a serialized request envelope, waits for a serialized response, and returns that response to the MCP tool method.

PipeServer lives on the host side. In the VSIX host, it accepts the pipe connection, reads the request envelope, dispatches the command, and writes a response.

At a high level, the client side looks like this:

using var pipe = new NamedPipeClientStream(".", _pipeName, PipeDirection.InOut, PipeOptions.Asynchronous);
await pipe.ConnectAsync(timeout: 5000, cancellationToken);

await writer.WriteLineAsync(JsonSerializer.Serialize(envelope, JsonOptions));
var responseJson = await reader.ReadLineAsync(cancellationToken);

And the server side listens for local pipe connections, then hands each connection to request handling:

pipe = new NamedPipeServerStream(
    PipeName,
    PipeDirection.InOut,
    NamedPipeServerStream.MaxAllowedServerInstances,
    PipeTransmissionMode.Byte,
    PipeOptions.Asynchronous);

pipe.WaitForConnection();
_ = Task.Run(() => HandleConnectionAsync(pipe, ct), CancellationToken.None);

The useful point is not the exact syntax. The useful point is the split of responsibility: the MCP server initiates a local pipe request, and the VSIX host accepts and dispatches it.

The Request Envelope

The named-pipe listener is not a chat endpoint. It expects a structured request envelope.

That envelope carries fields such as:

• Command
• RequestId
• Payload

The command tells the host what operation is being requested. The request ID gives the logs and responses a stable correlation point. The payload contains the typed request body for that operation.

This structure is what makes the bridge diagnosable. When a tool call fails, the operator can ask which request crossed which boundary instead of guessing from unstructured text.

How Dispatch Works

Once the pipe server has a request envelope, it dispatches by command name. It does not interpret prose or execute arbitrary instructions.

VsResponseBase response = envelope.Command switch
{
    PipeCommands.GetActiveDocument => await _vsService.GetActiveDocumentAsync(),
    PipeCommands.GetSelectedText => await _vsService.GetSelectedTextAsync(),
    PipeCommands.ListSolutionProjects => await _vsService.ListSolutionProjectsAsync(),
    PipeCommands.GetErrorList => await _vsService.GetErrorListAsync(),
    PipeCommands.ProposeTextEdit => await DispatchProposeEditAsync(envelope),
    _ => new VsResponseBaseUnknown { Success = false, ErrorMessage = $"Unknown command: {envelope.Command}" }
};

The current MCP surface is explicit and limited. Unknown, empty, malformed, or unsupported pipe commands fail closed instead of being dispatched.

Where Visual Studio Work Happens

The pipe server owns transport and dispatch. It does not need to own DTE or editor behavior directly.

Visual Studio-specific work is handled by the host service layer, such as VsService. That is where operations such as these belong:

• getting the active document,
• reading selected text,
• listing solution projects,
• reading the Error List,
• creating approval-gated edit proposals.

This keeps transport concerns separate from Visual Studio concerns. It also keeps the MCP server from needing direct knowledge of Visual Studio SDK details.

Activation and Startup Boundaries

The VSIX side must be active before VS-backed MCP tools can succeed. In live validation, the reliable operator path is to launch the Visual Studio Experimental Instance and open View -> Other Windows -> VS MCP Bridge. That activation path initializes the VSIX/tool-window side needed for the named pipe.

If the MCP server is running but the VSIX pipe side is inactive, that is not an MCP stdio failure. It is a named-pipe activation failure.

The current diagnostic path treats that case explicitly. Instead of appearing as an opaque timeout, the pipe client returns a structured activation diagnostic telling the operator to launch Visual Studio, open the VS MCP Bridge tool window, and retry the VS-backed tool.

That matters because a transport failure should identify the failed boundary:

• If stdio is broken, the AI client and MCP server are not talking correctly.
• If the named pipe is unavailable, the MCP server cannot reach the VSIX side.
• If command dispatch fails, the request reached the host but did not match an allowed operation.
• If VsService fails, the request reached Visual Studio-side execution but the host operation failed.

Request and Response Correlation

The named-pipe layer participates in the same anti-black-box logging discipline as the rest of the bridge. Requests carry IDs across the boundary so logs can be reconstructed later.

A useful trace should be able to answer:

• which MCP tool was called,
• which pipe command was sent,
• which request ID crossed the pipe,
• whether the pipe connected, timed out, or returned a structured failure,
• which host operation ran,
• how long each boundary took.

That is why the architecture emphasizes request IDs, operation names, elapsed timing, success or failure state, and durable trace artifacts. The goal is not more logging for its own sake. The goal is to make failure reconstruction practical.

Approval-Aware Flow Where It Matters

The named pipe does not approve tool execution by itself. It moves structured requests between local processes.

For Visual Studio edit operations, the VSIX proposal workflow remains approval-gated. MCP can propose edits, but applying them still requires explicit approval in the host UI.

For shared compiled bridge tools, approval-aware execution is a separate executor concern. A compiled tool descriptor can require approval, and BridgeToolExecutor owns policy evaluation, approval evaluation, execution, audit, correlation, and redaction for that path.

That means the named-pipe layer supports approval-aware architecture by preserving structured boundaries and correlation, but it is not the shared compiled-tool policy engine.

Relationship to MCP and BridgeToolExecutor

It helps to keep three boundaries separate:

• MCP stdio boundary: the AI client talks to VsMcpBridge.McpServer.
• Named-pipe boundary: VsMcpBridge.McpServer talks to the VSIX host for Visual Studio-backed tools.
• BridgeToolExecutor boundary: shared compiled tools run through policy, approval, execution, audit, redaction, and correlation seams.

Those boundaries are complementary. The named pipe keeps Visual Studio operations local to the VSIX. BridgeToolExecutor keeps compiled tool execution governed by a single shared policy and audit boundary. stdio keeps the AI client protocol isolated from both of those internal implementation details.

Failure Isolation and Troubleshooting

If you are debugging a VS-backed tool call, follow the boundary chain instead of treating the bridge as one black box:

1. Did the AI client successfully launch and speak to the MCP server over stdio?
2. Did the MCP server resolve the expected registered tool?
3. Did PipeClient attempt the expected command with a request ID?
4. Was the VSIX/tool-window side active and listening on the named pipe?
5. Did PipeServer accept and parse the request envelope?
6. Did the command dispatch to a known PipeCommands value?
7. Did VsService complete the host operation?
8. Did the response return through the pipe and then over MCP stdout?

This is the practical value of clean transport boundaries. Each step has a narrow responsibility, so the first missing or failing boundary can be found from logs and trace artifacts.

Related Mermaid Trace Sources

The repo already has Mermaid sources that support this post:

• vs-mcp-bridge-bootstrap-sequence.mmd shows the end-to-end path from VSIX startup through MCP stdio and the named-pipe handoff.
• vsix-activation-diagnostic-trace-20260516.mmd shows the inactive-pipe diagnostic and successful activation retry path.
• vsix-host-selected-text-trace-20260509.mmd shows a concrete VSIX-host operation with operation correlation.

Those .mmd files remain the diagram source of truth. This post references them directly instead of embedding generated images.

Why This Supports Future Extensibility

The named-pipe layer gives future work a stable place to preserve local host isolation. New VS-backed operations can stay explicit command-and-response paths. New compiled tools can continue to use BridgeToolExecutor for policy, approval, redaction, and audit. Additional diagnostics can attach to the existing correlation chain without polluting MCP stdout.

That is the main architectural benefit. The bridge can grow without collapsing the AI protocol, Visual Studio host operations, transport diagnostics, and tool security seams into one layer.

Takeaway

A named pipe listener is the local Visual Studio-side endpoint that waits for structured inter-process requests. In VS MCP Bridge, it exists so the VSIX can own Visual Studio operations while a separate MCP server process owns the AI-facing MCP stdio transport.

The short version is:

stdio gets into the MCP server
named pipes get into Visual Studio
BridgeToolExecutor governs shared compiled tool execution

Keeping those roles separate is what makes the bridge easier to diagnose, safer to extend, and more useful for observable AI tooling.