CoplayDev/unity-mcp · critical · SystemExit

1

1

Error message

--http-remote-hosted requires --api-key-validation-url or UNITY_MCP_API_KEY_VALIDATION_URL environment variable

What it means

A fatal startup validation in main.py: when --http-remote-hosted is enabled AND transport_mode is 'http' AND no API key validation URL is configured, the server aborts with SystemExit(1). Remote-hosted mode exposes the server to multiple users over the network, so it mandates an external API key validation endpoint to authenticate clients. Without it, the server refuses to start — this is a security guardrail, not a runtime error.

Source

Thrown at Server/src/main.py:848

        config.api_key_cache_ttl = 300.0

    # Service token for authenticating to validation endpoint
    config.api_key_service_token_header = (
        args.api_key_service_token_header
        or os.environ.get("UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER")
    )
    config.api_key_service_token = (
        args.api_key_service_token
        or os.environ.get("UNITY_MCP_API_KEY_SERVICE_TOKEN")
    )

    # Validate: remote-hosted HTTP mode requires API key validation URL
    if config.http_remote_hosted and config.transport_mode == "http" and not config.api_key_validation_url:
        logger.error(
            "--http-remote-hosted requires --api-key-validation-url or "
            "UNITY_MCP_API_KEY_VALIDATION_URL environment variable"
        )
        raise SystemExit(1)

    http_url = os.environ.get("UNITY_MCP_HTTP_URL", args.http_url)
    parsed_url = urlparse(http_url)

    # Allow individual host/port to override URL components
    http_host = args.http_host or os.environ.get(
        "UNITY_MCP_HTTP_HOST") or parsed_url.hostname or "127.0.0.1"

    # Safely parse optional environment port (may be None or non-numeric)
    _env_port_str = os.environ.get("UNITY_MCP_HTTP_PORT")
    try:
        _env_port = int(_env_port_str) if _env_port_str is not None else None
    except ValueError:
        logger.warning(
            "Invalid UNITY_MCP_HTTP_PORT value '%s', ignoring", _env_port_str)
        _env_port = None

    http_port = args.http_port or _env_port or parsed_url.port or 8080

View on GitHub (pinned to c21bf496bc)

Solutions

1. Provide the validation URL via CLI flag: add `--api-key-validation-url https://your-auth.example.com/validate` to the launch command.
2. Or set the environment variable: UNITY_MCP_API_KEY_VALIDATION_URL=https://your-auth.example.com/validate.
3. If you did not intend remote-hosted mode, remove --http-remote-hosted / UNITY_MCP_HTTP_REMOTE_HOSTED from the launch config.
4. Verify the validation endpoint is reachable and returns 200 for valid keys before starting the server.

Example fix

# before
python -m src.main --transport http --http-remote-hosted
# after
python -m src.main --transport http --http-remote-hosted \
  --api-key-validation-url https://auth.example.com/validate

# Validate required config before launching the server
import os
http_remote_hosted = os.environ.get("UNITY_MCP_HTTP_REMOTE_HOSTED", "").lower() in ("1", "true", "yes")
transport = os.environ.get("UNITY_MCP_TRANSPORT", "stdio")
validation_url = os.environ.get("UNITY_MCP_API_KEY_VALIDATION_URL", "")

if http_remote_hosted and transport == "http" and not validation_url:
    raise SystemExit(
        "Remote-hosted HTTP mode requires UNITY_MCP_API_KEY_VALIDATION_URL. "
        "Set it or disable --http-remote-hosted."
    )

When it happens

Trigger: Launching the server with `--http-remote-hosted --transport http` but omitting `--api-key-validation-url`; setting UNITY_MCP_HTTP_REMOTE_HOSTED=1 and UNITY_MCP_TRANSPORT=http env vars without UNITY_MCP_API_KEY_VALIDATION_URL; a deployment script that enables remote-hosted mode but forgets to pass the validation URL.

Common situations: Migrating from local (loopback) to a remote-hosted deployment and forgetting the auth dependency; a CI/deploy script that sets remote-hosted via env but not the validation URL; misreading the docs and assuming the validation URL is optional.

Related errors

• API key authentication required. Provide a valid X-API-Key h
• Failed to write config file '{path}': {ex.Message}
• The selected uvx executable does not exist
• The selected Claude CLI executable does not exist
• Invalid MCP base URL: {baseUrl}

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