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

> Unity MCP stdio vs HTTP transport: discover implementation and configuration for local and remote connections. Master CoplayDev/unity-mcp TransportManager for seamless workflows.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Unity MCP supports stdio for single-client local workflows and HTTP for multi-client remote connections, with [`TransportManager.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Services/Transport/TransportManager.cs)):

```csharp
public enum TransportMode
{
    Http,
    Stdio
}

```

## Core Implementation in TransportManager.cs

The `TransportManager` class ([`MCPForUnity/Editor/Services/Transport/TransportManager.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

```csharp
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`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

```csharp
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:

```csharp
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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

```json
// 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`](https://github.com/CoplayDev/unity-mcp/blob/main/TransportManager.cs)** provides the unified API (`StartAsync`, `StopAsync`, `GetState`) for managing both transports, ensuring clean lifecycle transitions.
- **[`McpConnectionSection.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/ClientConfigFormatTests.cs) test suite validates that these configurations conform to the MCP specification for each transport type.