Unity MCP stdio vs HTTP Transport Modes: Implementation and Configuration Guide

Unity MCP supports stdio for single-client local workflows and HTTP for multi-client remote connections, with TransportManager.cs orchestrating both modes through a unified StartAsync/StopAsync API.

The CoplayDev/unity-mcp repository implements a Model Context Protocol (MCP) bridge that relays messages between the Python MCP server and the Unity Editor. Understanding the differences between stdio and HTTP transport modes is essential for configuring your AI assistant integration, as each mode serves distinct architectural needs and security models.

What Are the Transport Modes?

Unity MCP provides two mutually exclusive transports for establishing the bridge connection:

• Stdio transport: Spawns a dedicated bridge process that communicates over standard input/output streams. This mode binds to a single process lifecycle and offers minimal network exposure, making it ideal for isolated, single-assistant workflows where only one AI client attaches to the Unity Editor.

• HTTP transport: Runs a lightweight HTTP WebSocket server inside the editor. Clients connect via http://localhost:<port> for local connections or remote URLs for distributed setups. This enables multi-assistant scenarios, HTTP-based tooling, and external clients that cannot utilize stdio pipes.

Both modes are defined in the TransportMode enum (lines 186-190 of MCPForUnity/Editor/Services/Transport/TransportManager.cs):

public enum TransportMode
{
    Http,
    Stdio
}

Core Implementation in TransportManager.cs

The TransportManager class (MCPForUnity/Editor/Services/Transport/TransportManager.cs) serves as the central orchestrator for transport lifecycle operations. It maintains separate client instances for each mode (_httpClient, _stdioClient) and exposes a consistent API regardless of the underlying protocol.

Key methods include:

• public async Task<bool> StartAsync(TransportMode mode): Lazily initializes the client via GetOrCreateClient and establishes the connection.
• public async Task StopAsync(TransportMode? mode = null): Gracefully terminates the specified transport, or both if no mode is provided.
• public async Task<bool> VerifyAsync(TransportMode mode): Performs health checks to validate connectivity.
• public TransportState GetState(TransportMode mode): Returns the current connection state (IsConnected, etc.).
• public bool IsRunning(TransportMode mode): Convenience wrapper for GetState(mode).IsConnected.

State tracking occurs in dedicated fields (_httpState, _stdioState), ensuring that switching between transports does not leak resources or leave orphaned processes.

UI Transport Selection via McpConnectionSection.cs

The Unity Editor interface for transport selection resides in MCPForUnity/Editor/Windows/Components/Connection/McpConnectionSection.cs. The UI presents a dropdown (transportDropdown) mapping to the TransportProtocol enum, which includes "Stdio", "HTTP Local", and "HTTP Remote" options.

When a user changes the selection (lines 124-148), the code executes an atomic switch:

var previous = (TransportProtocol)evt.previousValue;
var selected = (TransportProtocol)evt.newValue;
bool useHttp = selected != TransportProtocol.Stdio;

var stopMode = previous == TransportProtocol.Stdio ? TransportMode.Http : TransportMode.Stdio;
await TransportManager.StopAsync(stopMode);
await TransportManager.StartAsync(selected == TransportProtocol.Stdio ? TransportMode.Stdio : TransportMode.Http);

This ensures the previously active transport stops before the new one initializes, preventing port conflicts and resource contention. The UI also displays transport-mismatch warnings (lines 1088-1123) when the client's configured transport differs from the server-side setting.

BridgeControlService.cs Facade

For higher-level operations, MCPForUnity/Editor/Services/BridgeControlService.cs provides a simplified façade over the transport manager. This service exposes helper methods that both the CLI commands and Editor UI invoke:

await _transportManager.StartAsync(TransportMode.Http);   // Initialize WebSocket server
await _transportManager.StartAsync(TransportMode.Stdio); // Spawn stdio bridge process

This abstraction layer decouples UI components from direct transport implementation details.

Practical Usage Examples

Starting a Transport Programmatically

To initiate a transport from editor scripts or automation tools:

using MCPForUnity.Editor.Services;
using MCPForUnity.Editor.Services.Transport;

// Start the HTTP bridge for multi-client support
await MCPServiceLocator.TransportManager.StartAsync(TransportMode.Http);

// Verify connection status
bool isConnected = MCPServiceLocator.TransportManager.IsRunning(TransportMode.Http);

// Cleanup when finished
await MCPServiceLocator.TransportManager.StopAsync(TransportMode.Http);

Switching Transports via Editor UI

1. Open MCP For Unity → Settings in the Unity Editor menu
2. Locate the Transport dropdown (labeled "Stdio", "HTTP Local", or "HTTP Remote")
3. Select the desired mode—the UI automatically stops the former transport and starts the new one

The McpConnectionSection.cs handles the lifecycle transition automatically, including state validation and error surfacing.

Configuration Format Differences

The transport mode determines the JSON configuration structure exposed to MCP clients. According to TestProjects/UnityMCPTests/Assets/Tests/EditMode/Helpers/ClientConfigFormatTests.cs (lines 92-94), stdio configurations use command and args fields, while HTTP configurations specify a url field:

// Stdio configuration
{
  "command": "python",
  "args": ["-m", "unity_mcp"]
}

// HTTP configuration  
{
  "url": "http://localhost:8080/mcp"
}

When to Use Each Transport Mode

Choose stdio transport when:

• Running a single local AI assistant (Claude Desktop, etc.)
• Minimizing network attack surface is critical
• Operating in restricted environments where opening ports violates security policies

Choose HTTP transport when:

• Multiple AI clients must connect simultaneously
• External tools or services require HTTP/WebSocket access
• Remote development scenarios where the Unity Editor runs on a different machine than the AI client
• Integration with browser-based tools or cloud-based assistants

Summary

• Stdio transport spawns a process-based bridge using standard I/O streams, optimal for single-assistant, high-security local workflows.
• HTTP transport launches a WebSocket-capable server inside the editor, enabling multi-client connections and remote access via URL endpoints.
• TransportManager.cs provides the unified API (StartAsync, StopAsync, GetState) for managing both transports, ensuring clean lifecycle transitions.
• McpConnectionSection.cs implements the Editor UI for safe transport switching, automatically handling teardown of the previous mode.
• Configuration formats differ: stdio uses command/args while HTTP uses url, as validated in the project's unit tests.

Frequently Asked Questions

What is the difference between stdio and HTTP transport in Unity MCP?

Stdio transport launches a dedicated child process that communicates through stdin/stdout pipes, limiting connections to a single local client but requiring no network configuration. HTTP transport runs an embedded WebSocket server within the Unity Editor process, accepting multiple concurrent connections over TCP/IP but requiring port configuration and firewall allowances.

How do I switch between transport modes in the Unity Editor?

Navigate to MCP For Unity → Settings and select the desired option from the Transport dropdown. The McpConnectionSection.cs UI component automatically stops the currently active transport via TransportManager.StopAsync() before starting the new one, ensuring clean resource management and preventing port conflicts.

Can I run both stdio and HTTP transports simultaneously?

No, the transports are mutually exclusive by design. The TransportManager maintains separate state for each mode but the UI enforces single-transport operation to prevent resource contention and configuration ambiguity. Attempting to start a second transport while one is active triggers the automatic stop logic in McpConnectionSection.cs.

Where is the transport mode configuration stored?

The active transport selection persists through the TransportManager state and Unity Editor preferences, while the client-side configuration (whether to use stdio command/args or HTTP url) is generated dynamically based on the current mode. The ClientConfigFormatTests.cs test suite validates that these configurations conform to the MCP specification for each transport type.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}