Stdio
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.
How stdio Works in VS MCP Bridge
In the VS MCP Bridge architecture, stdio is the AI-facing MCP transport boundary. It is important, but it is not the whole bridge.
That distinction matters because “MCP over stdio” can sound as if the AI client is talking directly to Visual Studio. It is not. The AI client speaks MCP to a local server process over standard input and standard output. That server then uses a separate local named-pipe hop when a tool needs Visual Studio state.
This post explains the boundary, why stdout has to stay clean, and how the current implementation keeps diagnostics observable without corrupting the MCP protocol stream.
The Short Version
The runtime path for VS-backed MCP tools is:
AI client
-> MCP over stdio
VsMcpBridge.McpServer
-> JSON over named pipe
VsMcpBridge.Vsix
-> Visual Studio services / DTE / editor state
So stdio gets the request into the local MCP server. The named pipe gets VS-backed work into the VSIX. The two transports are intentionally separate.
Where stdio Is Enabled
The stdio transport is configured in the MCP host bootstrap:
builder.Services
.AddMcpServer()
.WithStdioServerTransport()
.WithTools<VsTools>();
That configuration lives in the VsMcpBridge.McpServer project, inside McpServerHost.Configure(...). The important line is WithStdioServerTransport().
That line tells the MCP host to exchange protocol messages through standard input and standard output instead of through HTTP, a socket listener, or a custom public endpoint.
What stdio Means Here
Standard input and standard output are process streams.
- stdin is how the AI client writes MCP requests into the server process.
- stdout is how the server process writes MCP responses back to the client.
That makes stdio a good fit for local AI tooling. The AI client can launch the MCP server as a worker process, keep it alive, write protocol messages to stdin, and read responses from stdout. The MCP server does not need to expose a network port for this local path.
The boundary is still a protocol boundary. stdout is not a casual logging stream once MCP is running over it.
Why stdout Must Stay Clean
One practical consequence of MCP over stdio is that stdout must be reserved for protocol traffic. If the server writes arbitrary diagnostic lines to stdout, the AI client can receive those lines as if they were MCP messages. That can make a healthy server look broken.
For that reason, diagnostics belong somewhere else:
- stderr when the host framework allows it safely,
- file logs under the local app-data logging paths,
- Visual Studio output panes and VSIX trace logs,
- structured trace artifacts when validating a workflow.
The current architecture treats clean stdout as part of the transport contract. Operational detail is preserved, but it is kept off the response stream that the MCP client is parsing.
What the Entry Point Does
The program entry point is intentionally small:
var builder = Host.CreateApplicationBuilder(args);
McpServerHost.Configure(builder);
await builder.Build().RunAsync();
Startup has a narrow job:
- Create the host builder.
- Register logging, the pipe client, MCP server support, stdio transport, and the VS-backed tool container.
- Build and run the host.
Once the host is running, the MCP tool surface is visible to the AI client over stdio.
What stdio Does Not Do
stdio does not make the MCP server a Visual Studio extension. It does not grant direct DTE access, load inside the Visual Studio process, or apply edits in the editor.
Those responsibilities stay on the VSIX side. The MCP server process stays outside Visual Studio and acts as the local AI-facing adapter.
That separation is one of the core architecture choices in the project:
- MCP protocol work lives in
VsMcpBridge.McpServer.
- Visual Studio API work lives in
VsMcpBridge.Vsix.
- Shared compiled bridge tools execute through
BridgeToolExecutor when they use the shared tool catalog/executor path.
stdio is a transport. It is not the policy, approval, audit, or redaction boundary for compiled bridge tools. That boundary remains BridgeToolExecutor.
How VS-Backed Tool Calls Cross the Boundary
The MCP host exposes the VS-backed tool container registered with WithTools<VsTools>(). That class contains explicit MCP tools such as:
vs_get_active_documentvs_get_selected_textvs_list_solution_projectsvs_get_error_listvs_propose_text_editvs_propose_text_edits
From the AI client’s perspective, those are MCP tools. The request arrives over stdin, the MCP host resolves the method, and the method executes inside the VsMcpBridge.McpServer process.
For Visual Studio-backed operations, the method still does not call Visual Studio directly. It forwards a structured request through the pipe client.
The Named-Pipe Hop
Inside VsTools, the VS-backed methods use an injected IPipeClient. That client connects to the VSIX-hosted named-pipe side:
using var pipe = new NamedPipeClientStream(".", _pipeName, PipeDirection.InOut, PipeOptions.Asynchronous);
await pipe.ConnectAsync(timeout: 5000, cancellationToken);
The full call path is layered:
- The AI client calls an MCP tool over stdio.
- The MCP host routes the call to a
VsTools method.
- The method uses
PipeClient to connect to the VSIX over the local named pipe.
- The VSIX dispatches the known pipe command and performs the Visual Studio-side operation.
- The VSIX returns a structured response through the pipe.
- The MCP server writes the MCP response back over stdout.
This is why stdio and the named pipe should be debugged separately. A stdio failure means the AI client and MCP server are not communicating correctly. A pipe failure means the MCP server could not reach the VSIX side.
The Activation Boundary
The named-pipe side is initialized by the Visual Studio extension. For live VS-backed tool calls, the operator must launch the Visual Studio Experimental Instance and open View -> Other Windows -> VS MCP Bridge so the VSIX/tool-window path initializes the local pipe server.
If that pipe side is inactive, the current MCP server returns an activation-focused diagnostic instead of leaving the operator with an opaque timeout. The diagnostic points to the activation steps: launch the Experimental Instance, open the VS MCP Bridge tool window, then retry the VS-backed tool.
That message is still returned as a structured tool failure. The transport does not change, and the server does not start adding retry loops or writing troubleshooting text to stdout outside the MCP response.
Correlation and Trace-Only Diagnostics
Because stdio needs clean protocol output, observability depends on structured diagnostics outside stdout. Current traces preserve request IDs, correlation IDs, operation names, timing, and success or failure outcomes across the relevant boundary.
For the inactive-pipe path, the useful evidence is not a random console line. It is the reconstructable chain:
MCP tool request received
PipeClient attempted named-pipe connection
named pipe was unavailable
activation diagnostic returned
correlation/request metadata preserved
no raw payload or secret values disclosed
That is the anti-black-box discipline used throughout the project. A failure should be explainable from durable logs, trace artifacts, and documented workflow boundaries, not from guessing which process happened to be awake.
Related Mermaid Trace Sources
The repo already has Mermaid sources that make this boundary easier to inspect:
Those .mmd files are the diagram source of truth. This post references them instead of embedding a derived image so the article stays aligned with the durable trace artifacts.
How This Relates to BridgeToolExecutor
The stdio server exposes VS-backed tools directly through the MCP tool container, and those tools cross into the VSIX over the named pipe. Separately, the shared bridge tool architecture has compiled tools, descriptors, capability metadata, approval requirements, secret-reference awareness, redaction, audit envelopes, and classification metadata.
Those shared compiled tools flow through BridgeToolExecutor. That executor is the policy, approval, execution, audit, correlation, and redaction boundary for that path.
The important distinction is:
- stdio is how an AI client talks MCP to the local server process.
- named pipes are how VS-backed MCP tools reach the VSIX.
- BridgeToolExecutor is the shared execution/security boundary for compiled bridge tools.
Keeping those responsibilities separate is what lets the architecture grow without turning transport code, Visual Studio integration, and security policy into one indistinct layer.
What to Remember When Studying This Code
If you are learning the system, keep these files and roles in mind:
Program.cs starts the MCP server host.McpServerHost.Configure(...) wires logging, stdio transport, the pipe client, and the MCP tool surface.VsTools defines the VS-backed MCP tools exposed over stdio.PipeClient bridges from the MCP server process into the VSIX.- The VSIX owns Visual Studio APIs, editor state, proposal application, and the named-pipe server side.
BridgeToolExecutor owns the shared compiled-tool policy and audit boundary.
Once those layers are clear, the implementation is much easier to reason about. The bridge is not one process doing everything. It is a set of local boundaries with explicit responsibilities.
Takeaway
In VS MCP Bridge, stdio is the process-to-process protocol transport that lets an AI client speak MCP to the local server host. The server then uses a separate local named-pipe boundary for Visual Studio-backed operations.
The cleanest mental model is:
stdio gets into the MCP server
named pipes get into Visual Studio
BridgeToolExecutor governs shared compiled tool execution
That separation keeps the bridge observable, debuggable, and easier to evolve. stdout stays clean for MCP. Diagnostics stay reconstructable. Visual Studio work stays in the VSIX. Shared tool execution keeps its own policy and audit boundary.