CoplayDev/unity-mcp · error · ValueError

HTTP transport requires command arguments

Error message

HTTP transport requires command arguments

What it means

Raised by send_with_unity_instance when the server is in HTTP transport mode but the caller passed no positional arguments, so there is no command_type to send. The HTTP code path needs at least the command name as args[0]; without it the request cannot be constructed.

Source

Thrown at Server/src/transport/unity_transport.py:51

            return None
        service = ApiKeyService.get_instance()
        result = await service.validate(api_key)
        return result.user_id if result.valid else None
    except Exception as e:
        logger.debug("Failed to resolve user_id from HTTP request: %s", e)
        return None


async def send_with_unity_instance(
    send_fn: Callable[..., Awaitable[T]],
    unity_instance: str | None,
    *args,
    user_id: str | None = None,
    **kwargs,
) -> T:
    if _is_http_transport():
        if not args:
            raise ValueError("HTTP transport requires command arguments")
        command_type = args[0]
        params = args[1] if len(args) > 1 else kwargs.get("params")
        if params is None:
            params = {}
        if not isinstance(params, dict):
            raise TypeError(
                "Command parameters must be a dict for HTTP transport")

        # Auto-resolve user_id from HTTP request API key (remote-hosted mode)
        if user_id is None:
            user_id = await _resolve_user_id_from_request()

        # Auth check
        if config.http_remote_hosted and not user_id:
            return normalize_unity_response(
                MCPResponse(
                    success=False,
                    error="auth_required",

View on GitHub (pinned to c21bf496bc)

Solutions

1. Pass the command_type as the first positional arg: send_with_unity_instance(send_fn, instance, 'manage_gameobject', params).
2. If authoring a wrapper, assert args is non-empty before dispatching in HTTP mode.
3. Keep the stdio and HTTP call signatures identical (both positional) to avoid this branch.

Example fix

// before
await send_with_unity_instance(send_fn, instance, command_type='manage_gameobject', params=p)
// after
await send_with_unity_instance(send_fn, instance, 'manage_gameobject', p)

if _is_http_transport() and not args:
    raise ValueError('command_type is required as the first positional arg in HTTP mode')

def has_command_type(args: tuple) -> bool:
    return len(args) >= 1

try:
    await send_with_unity_instance(send_fn, instance, *args)
except ValueError as e:
    if 'requires command arguments' in str(e):
        await send_with_unity_instance(send_fn, instance, command_type, params)

When it happens

Trigger: _is_http_transport() is true and the function was called as send_with_unity_instance(send_fn, instance) with nothing in *args. The guard at unity_transport.py:49-50 fires.

Common situations: A tool wrapper called send_with_unity_instance passing command_type and params only as kwargs (command_type=, params=) instead of positionally; refactor forgot the leading positional command name.

Related errors

• Port-based targeting ('{value}') is not supported in HTTP tr
• Command parameters must be a dict for HTTP transport
• Color array must have 3 or 4 elements.
• Port must be positive.
• Port {port} is already in use.

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