CoplayDev/unity-mcp · error · InvalidOperationException

Invalid MCP base URL: {baseUrl}

Error message

Invalid MCP base URL: {baseUrl}

What it means

Thrown by BuildWebSocketUri when the configured MCP server base URL cannot be parsed as an absolute URI (Uri.TryCreate with UriKind.Absolute fails). The transport needs a valid http:// or https:// URL to convert into a ws:// or wss:// endpoint, after which it rewrites bind-only hosts (0.0.0.0/::) to loopback and appends /hub/plugin. Any input that is not a scheme-prefixed absolute URL is rejected.

Source

Thrown at MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:826

                    {
                        _state = TransportState.Connected(TransportDisplayName, sessionId: _sessionId, details: _endpointUri.ToString());
                        _isConnected = true;
                        McpLog.Info("[WebSocket] Reconnected to MCP server", false);
                        return;
                    }
                }
            }
            finally
            {
                Interlocked.Exchange(ref _isReconnectingFlag, 0);
            }
        }

        private static Uri BuildWebSocketUri(string baseUrl)
        {
            if (!Uri.TryCreate(baseUrl, UriKind.Absolute, out var httpUri))
            {
                throw new InvalidOperationException($"Invalid MCP base URL: {baseUrl}");
            }

            // Replace bind-only addresses for client connections
            // 0.0.0.0 and :: are only valid for server binding, not client connections
            string host = httpUri.Host;
            if (host == "0.0.0.0")
            {
                McpLog.Warn($"[WebSocket] Base URL host '{host}' is bind-only; using '127.0.0.1' for client connection.");
                host = "127.0.0.1";
            }
            else if (host == "::")
            {
                McpLog.Warn($"[WebSocket] Base URL host '{host}' is bind-only; using '::1' for client connection.");
                host = "::1";
            }

            var builder = new UriBuilder(httpUri)
            {

View on GitHub (pinned to c21bf496bc)

Solutions

1. Set the base URL with an explicit scheme, e.g. 'http://127.0.0.1:6500'.
2. Open MCP for Unity Advanced Settings and correct the Server URL field.
3. Remove trailing slashes, fragments, or stray characters from the URL.
4. If driving programmatically, ensure the value is non-empty and absolute before passing it to the transport.

Example fix

// before
var baseUrl = "localhost:6500";
// after
var baseUrl = "http://localhost:6500";

if (string.IsNullOrWhiteSpace(baseUrl) || !Uri.TryCreate(baseUrl, UriKind.Absolute, out _))
{
    throw new ArgumentException($"Base URL must be an absolute URI, got: {baseUrl}");
}

When it happens

Trigger: Calling Start/connect with a baseUrl that is empty, relative (e.g. 'localhost:6500'), missing its scheme ('//host/path'), or contains characters that break URI parsing. The baseUrl originates from MCP for Unity Advanced Settings (Server URL).

Common situations: Developer enters host:port without a scheme in Advanced Settings; a stale config survived a server move; an env var or serialized setting resolved to empty; copy-paste included trailing whitespace or a path fragment.

Related errors

• Failed to write config file '{path}': {ex.Message}
• The selected uvx executable does not exist
• The selected Claude CLI executable does not exist
• Repo URL is not a recognized GitHub repository URL: {repoUrl
• Remote directory not found: {normalizedSubdir}

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/7b6e1f6f5feaf296. Report an issue: GitHub.