mcpforunityserver 9.3.0b20260129121506__py3-none-any.whl → 9.3.0b20260131003150__py3-none-any.whl

{mcpforunityserver-9.3.0b20260129121506.dist-info → mcpforunityserver-9.3.0b20260131003150.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 9.3.0b20260129121506
+Version: 9.3.0b20260131003150
 Summary: MCP for Unity Server: A Unity package for Unity Editor integration via the Model Context Protocol (MCP).
 Author-email: Marcus Sanatan <msanatan@gmail.com>, David Sarno <david.sarno@gmail.com>, Wu Shutong <martinwfire@gmail.com>
 License-Expression: MIT
@@ -154,12 +154,124 @@ uv run src/main.py --transport stdio
 
 ## Configuration
 
-The server connects to Unity Editor automatically when both are running. No additional configuration needed.
+The server connects to Unity Editor automatically when both are running. Most users do not need to change any settings.
+
+### CLI options
+
+These options apply to the `mcp-for-unity` command (whether run via `uvx`, Docker, or `python src/main.py`).
+
+- `--transport {stdio,http}` - Transport protocol (default: `stdio`)
+- `--http-url URL` - Base URL used to derive host/port defaults (default: `http://localhost:8080`)
+- `--http-host HOST` - Override HTTP bind host (overrides URL host)
+- `--http-port PORT` - Override HTTP bind port (overrides URL port)
+- `--http-remote-hosted` - Treat HTTP transport as remotely hosted
+  - Requires API key authentication (see below)
+  - Disables local/CLI-only HTTP routes (`/api/command`, `/api/instances`, `/api/custom-tools`)
+  - Forces explicit Unity instance selection for MCP tool/resource calls
+  - Isolates Unity sessions per user
+- `--api-key-validation-url URL` - External endpoint to validate API keys (required when `--http-remote-hosted` is set)
+- `--api-key-login-url URL` - URL where users can obtain/manage API keys (served by `/api/auth/login-url`)
+- `--api-key-cache-ttl SECONDS` - Cache duration for validated keys (default: `300`)
+- `--api-key-service-token-header HEADER` - Header name for server-to-auth-service authentication (e.g. `X-Service-Token`)
+- `--api-key-service-token TOKEN` - Token value sent to the auth service for server authentication
+- `--default-instance INSTANCE` - Default Unity instance to target (project name, hash, or `Name@hash`)
+- `--project-scoped-tools` - Keep custom tools scoped to the active Unity project and enable the custom tools resource
+- `--unity-instance-token TOKEN` - Optional per-launch token set by Unity for deterministic lifecycle management
+- `--pidfile PATH` - Optional path where the server writes its PID on startup (used by Unity-managed terminal launches)
+
+### Environment variables
+
+- `UNITY_MCP_TRANSPORT` - Transport protocol: `stdio` or `http`
+- `UNITY_MCP_HTTP_URL` - HTTP server URL (default: `http://localhost:8080`)
+- `UNITY_MCP_HTTP_HOST` - HTTP bind host (overrides URL host)
+- `UNITY_MCP_HTTP_PORT` - HTTP bind port (overrides URL port)
+- `UNITY_MCP_HTTP_REMOTE_HOSTED` - Enable remote-hosted mode (`true`, `1`, or `yes`)
+- `UNITY_MCP_DEFAULT_INSTANCE` - Default Unity instance to target (project name, hash, or `Name@hash`)
+- `UNITY_MCP_SKIP_STARTUP_CONNECT=1` - Skip initial Unity connection attempt on startup
+
+API key authentication (remote-hosted mode):
+
+- `UNITY_MCP_API_KEY_VALIDATION_URL` - External endpoint to validate API keys
+- `UNITY_MCP_API_KEY_LOGIN_URL` - URL where users can obtain/manage API keys
+- `UNITY_MCP_API_KEY_CACHE_TTL` - Cache TTL for validated keys in seconds (default: `300`)
+- `UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER` - Header name for server-to-auth-service authentication
+- `UNITY_MCP_API_KEY_SERVICE_TOKEN` - Token value sent to the auth service for server authentication
+
+Telemetry:
+
+- `DISABLE_TELEMETRY=1` - Disable anonymous telemetry (opt-out)
+- `UNITY_MCP_DISABLE_TELEMETRY=1` - Same as `DISABLE_TELEMETRY`
+- `MCP_DISABLE_TELEMETRY=1` - Same as `DISABLE_TELEMETRY`
+- `UNITY_MCP_TELEMETRY_ENDPOINT` - Override telemetry endpoint URL
+- `UNITY_MCP_TELEMETRY_TIMEOUT` - Override telemetry request timeout (seconds)
+
+### Examples
+
+**Stdio (default):**
 
-**Environment Variables:**
+```bash
+uvx --from mcpforunityserver mcp-for-unity --transport stdio
+```
+
+**HTTP (local):**
+
+```bash
+uvx --from mcpforunityserver mcp-for-unity --transport http --http-host 127.0.0.1 --http-port 8080
+```
+
+**HTTP (remote-hosted with API key auth):**
+
+```bash
+uvx --from mcpforunityserver mcp-for-unity \
+  --transport http \
+  --http-host 0.0.0.0 \
+  --http-port 8080 \
+  --http-remote-hosted \
+  --api-key-validation-url https://auth.example.com/api/validate-key \
+  --api-key-login-url https://app.example.com/api-keys
+```
+
+**Disable telemetry:**
+
+```bash
+DISABLE_TELEMETRY=1 uvx --from mcpforunityserver mcp-for-unity --transport stdio
+```
+
+---
+
+## Remote-Hosted Mode
+
+When deploying the server as a shared remote service (e.g. for a team or Asset Store users), enable `--http-remote-hosted` to activate API key authentication and per-user session isolation.
+
+**Requirements:**
+
+- An external HTTP endpoint that validates API keys. The server POSTs `{"api_key": "..."}` and expects `{"valid": true, "user_id": "..."}` or `{"valid": false}` in response.
+- `--api-key-validation-url` must be provided (or `UNITY_MCP_API_KEY_VALIDATION_URL`). The server exits with code 1 if this is missing.
+
+**What changes in remote-hosted mode:**
+
+- All MCP tool/resource calls and Unity plugin WebSocket connections require a valid `X-API-Key` header.
+- Each user only sees Unity instances that connected with their API key (session isolation).
+- Auto-selection of a sole Unity instance is disabled; users must explicitly call `set_active_instance`.
+- CLI REST routes (`/api/command`, `/api/instances`, `/api/custom-tools`) are disabled.
+- `/health` and `/api/auth/login-url` remain accessible without authentication.
+
+**MCP client config with API key:**
+
+```json
+{
+  "mcpServers": {
+    "UnityMCP": {
+      "url": "http://remote-server:8080/mcp",
+      "headers": {
+        "X-API-Key": "<your-api-key>"
+      }
+    }
+  }
+}
+```
 
-- `DISABLE_TELEMETRY=true` - Opt out of anonymous usage analytics
-- `LOG_LEVEL=DEBUG` - Enable detailed logging (default: INFO)
+For full details, see [Remote Server Auth Guide](../docs/guides/REMOTE_SERVER_AUTH.md) and [Architecture Reference](../docs/reference/REMOTE_SERVER_AUTH_ARCHITECTURE.md).
 
 ---
 

{mcpforunityserver-9.3.0b20260129121506.dist-info → mcpforunityserver-9.3.0b20260131003150.dist-info}/RECORD

@@ -1,4 +1,4 @@
-main.py,sha256=EoHA0upWjtQzuoOgN5BfNmGL6bIVnFQjRW5PHO5EmjY,29265
+main.py,sha256=xNuZrgxhsjVOYl1C-NBzpW-eb8YW3_m_E2Npz9a5vao,35040
 cli/__init__.py,sha256=f2HjXqR9d8Uhibru211t9HPpdrb_1vdDC2v_NwF_eqA,63
 cli/main.py,sha256=V_VFa8tA-CDHNv9J5NzNSLxRuEGjRVZWDe4xn6rYdog,8457
 cli/commands/__init__.py,sha256=xQHf6o0afDV2HsU9gwSxjcrzS41cMCSGZyWYWxblPIk,69
@@ -24,40 +24,42 @@ cli/commands/vfx.py,sha256=gdx5a_N7Ulu960xjaJIV0E_1Ii422C211KaipoRO6nQ,14453
 cli/utils/__init__.py,sha256=Gbm9hYC7UqwloFwdirXgo6z1iBktR9Y96o3bQcrYudc,613
 cli/utils/config.py,sha256=_k3XAFmXG22sv8tYIb5JmO46kNl3T1sGqFptySAayfc,1550
 cli/utils/confirmation.py,sha256=7NGu0I5ogowpdWRTUndn3g5nmWmJM9mV3e0wWMLJwA8,1234
-cli/utils/connection.py,sha256=RBSOK7WotKgokj-wewsqnKT5rwS0_DhsqXqZrFZWUXo,8534
+cli/utils/connection.py,sha256=fx2o3J9AI6HdSC6rRDKh6KO8sPmBWkzR-ElY1dDkhes,8123
 cli/utils/constants.py,sha256=xCyRMY1L3cc-sbCyl-TGyqkY5hMCOl5tU6L4ZVbN9w4,1046
 cli/utils/output.py,sha256=96daU55ta_hl7UeOhNh5Iy7OJ4psbdR9Nfx1-q2k3xA,6370
 cli/utils/parsers.py,sha256=mnpH2bhZn3L3Lyl8e7Sh7Zr2UW9Xzu3aUuCaLxpV2pk,3430
 cli/utils/suggestions.py,sha256=n6KG3Mrvub28X9rPFYFLRTtZ6HePp3PhhAeojG2WOJw,929
 core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-core/config.py,sha256=kE7yg_89QQck3zScWNjvrq7CnfYt6uLS0VdxK7AJ70o,1453
+core/config.py,sha256=VlCLUFPm73DfInCVZkJFq4_7KZKVqSFbDS-n0HMA8WA,2118
+core/constants.py,sha256=PhZs926Nie7Muigju1xkVBynVaUktZlP9lJMHgu4_to,114
 core/logging_decorator.py,sha256=D9CD7rFvQz-MBG-G4inizQj0Ivr6dfc9RBmTrw7q8mI,1383
 core/telemetry.py,sha256=zIjmQKUNW0S822SSlkXyjjCIuX0ZpSTaZP4pAU0rCjw,20426
 core/telemetry_decorator.py,sha256=ycSTrzVNCDQHSd-xmIWOpVfKFURPxpiZe_XkOQAGDAo,6705
-mcpforunityserver-9.3.0b20260129121506.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
-models/__init__.py,sha256=JlscZkGWE9TRmSoBi99v_LSl8OAFNGmr8463PYkXin4,179
+mcpforunityserver-9.3.0b20260131003150.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
+models/__init__.py,sha256=J2ozraI5aDkqLb53KvXjTDaWgh_xVFxpWrcRMekOwPk,231
 models/models.py,sha256=heXuvdBtdats1SGwW8wKFFHM0qR4hA6A7qETn5s9BZ0,1827
-models/unity_response.py,sha256=oJ1PTsnNc5VBC-9OgM59C0C-R9N-GdmEdmz_yph4GSU,1454
+models/unity_response.py,sha256=xvgJhJ3pS8-ATQhnU5owijgO4141UW59f5dQm1ohVew,2278
 services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+services/api_key_service.py,sha256=Wq8BJDHXurN0hSiotqI37ta7G-Q9QAxHCD5hHbokxYs,8755
 services/custom_tool_service.py,sha256=WJxljL-hdJE5GMlAhVimHVhQwwnWHCd0StgWhWEFgaI,18592
 services/registry/__init__.py,sha256=QCwcYThvGF0kBt3WR6DBskdyxkegJC7NymEChgJA-YM,470
 services/registry/resource_registry.py,sha256=T_Kznqgvt5kKgV7mU85nb0LlFuB4rg-Tm4Cjhxt-IcI,1467
 services/registry/tool_registry.py,sha256=9tMwOP07JE92QFYUS4KvoysO0qC9pkBD5B79kjRsSPw,1304
 services/resources/__init__.py,sha256=G8uSEYJtiyX3yg0QsfoeGdDXOdbU89l5m0B5Anay1Fc,3054
-services/resources/active_tool.py,sha256=6m65iPCD1Iqmp4xqpDKvPErfOJg7Gl3XU5vMyAVcdj8,1521
+services/resources/active_tool.py,sha256=O2tKtId1-UCZXFAVigIN4WzuiihmyZe24sCGn1k16HA,1558
 services/resources/custom_tools.py,sha256=uujlJEuqv5svCvSZLILgiY6hiiWZqWHVzTBJpTTL3as,1751
-services/resources/editor_state.py,sha256=LZLmljdHQC7nQcA-YYtoRnpy1xDiiAzo4_iU69TgsH8,10858
+services/resources/editor_state.py,sha256=OEPdb7VFFzk6LGN1r5FouBFv4sQdfKs-8sMKZxXCHwA,11004
 services/resources/gameobject.py,sha256=cviektt_GHmwgria5pkvNrzvD5-6hzBi64Ogm0YGIv8,9356
-services/resources/layers.py,sha256=e3bDhfJ0ZjtUagHhraI35GrzrDnzXrRHnDeobmnbniw,1123
-services/resources/menu_items.py,sha256=01LIVHA96bswYGXyLZzGFw3suDqftsBanhy_lkUB2H0,1054
+services/resources/layers.py,sha256=6CjGfHH2XqLX6FYAoBLgePZH3srVO-9psZV8TJ93Okw,1160
+services/resources/menu_items.py,sha256=tNyHlqC9mFkllN3JW9fyouecTvnV4YbnlSAysbAjVbQ,1091
 services/resources/prefab.py,sha256=4TLEBsrlnQdi5FOKWZZ9eesiUCG5Ryxh7FZvd02FcTc,7434
-services/resources/prefab_stage.py,sha256=YALZrfZh4zpV_tEfQI7sUR6ETLnz8qeTN--gwYxk_y8,1430
-services/resources/project_info.py,sha256=NaHb9v5n-2vi3woMxioMXbgpy1tBcmh2bh0RZOTxtC4,1364
-services/resources/selection.py,sha256=HxmpN0RAb6Op0r4kqqRsizahP5L3Hj8V1baRa3uaKpU,1884
-services/resources/tags.py,sha256=f50DzILLNQsUJ44ooomwIGasrcntbKJgT7boqrU4b5s,1090
-services/resources/tests.py,sha256=KOm1vFcDPAXi21rDRQ1hQmifs1T9Xnd0zUp-BcBrBxo,3458
-services/resources/unity_instances.py,sha256=8vLA5oR2VpeLRjuxHk-_J3eopLhuNpGEoJyCvyUAOXg,4386
-services/resources/windows.py,sha256=inD7zMB3R4Tip_92pCDtKGD7clzsGKOGkdmv4rKmygA,1470
+services/resources/prefab_stage.py,sha256=APVPbzxSO4vUR0YgYDi4WI_woywqoc0KcTyUwgbGmJQ,1467
+services/resources/project_info.py,sha256=xGSFTxOs4y7ok7iO3XVdGhxxyjAXpg1czbapybqp-NI,1401
+services/resources/selection.py,sha256=E2thI4vWqk2SE3gm6mcDvYWSG0UuRpC1tja2Y6J2BRc,1921
+services/resources/tags.py,sha256=fROK2Bj9VBiyQSQt0jdXxYatX-3d4vtAH8i6Zhgj5Vw,1127
+services/resources/tests.py,sha256=6aqhZWxO6YPMGBzaw_dxMUm1wCJMFRNLeu6Nf_wXieo,3474
+services/resources/unity_instances.py,sha256=Ix6YtTWKnTLXZ4v4mrn_d0IhLr7gcjfe9d605zf2V5w,4564
+services/resources/windows.py,sha256=UT8-CDstsBXyggzJ8A9pVFIqNr8jr9oP77rOEBsWQCk,1507
 services/state/external_changes_scanner.py,sha256=ZiXu8ZcK5B-hv7CaJLmnEIa9JxzgOBpdmrsRDY2eK5I,9052
 services/tools/__init__.py,sha256=J-woLzm3aLF0uPC1-VroqG7QV9xLXHDmVYee2ZXuCgk,2746
 services/tools/batch_execute.py,sha256=hjh67kgWvQDHyGd2N-Tfezv9WAj5x_pWTt_Vybmmq7s,3501
@@ -83,21 +85,21 @@ services/tools/read_console.py,sha256=ps23debJcQkj3Ap-MqTYVhopYnKGspJs9QHLJHZAAk
 services/tools/refresh_unity.py,sha256=KrRA8bmLkDLFO1XBv2NmagQAp1dmyaXdUAap567Hcv4,7100
 services/tools/run_tests.py,sha256=Wd7hNZqy-OOZ9ZedonxUJ5bVlhta_aOEmD-2uxmrmyM,11743
 services/tools/script_apply_edits.py,sha256=0f-SaP5NUYGuivl4CWHjR8F-CXUpt3-5qkHpf_edn1U,47677
-services/tools/set_active_instance.py,sha256=pdmC1SxFijyzzjeEyC2N1bXk-GNMu_iXsbCieIpa-R4,4242
+services/tools/set_active_instance.py,sha256=j_d0GhFwhBh-HwoNKzrice1haNyWPdK-RtVrNasYH7c,4408
 services/tools/utils.py,sha256=ETCiNnWdMZEtnJcDD-CtPsCJ7TBp5x5sPsYuhufkxac,13962
 transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 transport/models.py,sha256=2tnK0Wc-IzvlOS0a04VB3WtuSlAAHeLVFfOnNFHGnhw,1311
-transport/plugin_hub.py,sha256=Kykqnydk_KkCSICaJGE8XQulr7sZeNcIgPOHjtdbjHM,23783
-transport/plugin_registry.py,sha256=L6xl7Ok9rtSW9xwSSKTFjWS7Duu1g4c-qfgfnn6y-sQ,4528
-transport/unity_instance_middleware.py,sha256=DD8gs-peMRmRJz9CYwaHEh4m75LTYPDjVuKuw9sArBw,10438
-transport/unity_transport.py,sha256=RKMH0NYPqTU3rpjXUPUkzZsdWhJqyVaHmkLswab4bGg,2135
+transport/plugin_hub.py,sha256=Xe0Vn1Df7Ks4KmRs3_waheUWuaQnT_DMLELA1tCnqHs,28449
+transport/plugin_registry.py,sha256=Zn2QaDbpDj9Ad-oXs3q7CXxnZz3mc5SJ61GzIToEBPI,7160
+transport/unity_instance_middleware.py,sha256=vdbX28eU6ddxEiPdgtv275Q1qcIJzuyYxQnNE-KXXnc,11837
+transport/unity_transport.py,sha256=MK7eG3JU5zEGF2w5ntIBqxCvLy7cv-E5tlymqcQC8UA,3319
 transport/legacy/port_discovery.py,sha256=JDSCqXLodfTT7fOsE0DFC1jJ3QsU6hVaYQb7x7FgdxY,12728
 transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEhZvSyl_uf0A,2313
 transport/legacy/unity_connection.py,sha256=FE9ZQfYMhHvIxBycr_DjI3BKvuEdORXuABnCE5Q2tjQ,36733
 utils/focus_nudge.py,sha256=0MCOms-SxUW7sN2hT3syy1epMdli2zc-6UHBICAfBSM,21330
 utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
-mcpforunityserver-9.3.0b20260129121506.dist-info/METADATA,sha256=NhUC2AYe0dyaYPjuAkHQN1wksQiDGTHHM_8k8IvcEw4,6750
-mcpforunityserver-9.3.0b20260129121506.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mcpforunityserver-9.3.0b20260129121506.dist-info/entry_points.txt,sha256=pPm70RXQvkt3uBhPOtViDa47ZTA03RaQ6rwXvyi8oiI,70
-mcpforunityserver-9.3.0b20260129121506.dist-info/top_level.txt,sha256=3-A65WsmBO6UZYH8O5mINdyhhZ63SDssr8LncRd1PSQ,46
-mcpforunityserver-9.3.0b20260129121506.dist-info/RECORD,,
+mcpforunityserver-9.3.0b20260131003150.dist-info/METADATA,sha256=9JlYrKIHsH0CAaGJUXtHikB_kUs9rWYjmJoPDYmvlkQ,11877
+mcpforunityserver-9.3.0b20260131003150.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mcpforunityserver-9.3.0b20260131003150.dist-info/entry_points.txt,sha256=pPm70RXQvkt3uBhPOtViDa47ZTA03RaQ6rwXvyi8oiI,70
+mcpforunityserver-9.3.0b20260131003150.dist-info/top_level.txt,sha256=3-A65WsmBO6UZYH8O5mINdyhhZ63SDssr8LncRd1PSQ,46
+mcpforunityserver-9.3.0b20260131003150.dist-info/RECORD,,

models/__init__.py

@@ -1,4 +1,4 @@
 from .models import MCPResponse, UnityInstanceInfo
-from .unity_response import normalize_unity_response
+from .unity_response import normalize_unity_response, parse_resource_response
 
-__all__ = ['MCPResponse', 'UnityInstanceInfo', 'normalize_unity_response']
+__all__ = ['MCPResponse', 'UnityInstanceInfo', 'normalize_unity_response', 'parse_resource_response']

models/unity_response.py

@@ -1,7 +1,9 @@
 """Utilities for normalizing Unity transport responses."""
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Type
+
+from models.models import MCPResponse
 
 
 def normalize_unity_response(response: Any) -> Any:
@@ -45,3 +47,24 @@ def normalize_unity_response(response: Any) -> Any:
         normalized["error"] = message or "Unity command failed"
 
     return normalized
+
+
+def parse_resource_response(response: Any, typed_cls: Type[MCPResponse]) -> MCPResponse:
+    """Parse a Unity response into a typed response class.
+
+    Returns a base ``MCPResponse`` for error responses so that typed subclasses
+    with strict ``data`` fields (e.g. ``list[str]``) don't raise Pydantic
+    validation errors when ``data`` is ``None``.
+    """
+    if not isinstance(response, dict):
+        return response
+
+    # Detect errors from both normalized (success=False) and raw (status="error") shapes.
+    if response.get("success") is False or response.get("status") == "error":
+        return MCPResponse(
+            success=False,
+            error=response.get("error"),
+            message=response.get("message"),
+        )
+
+    return typed_cls(**response)

services/api_key_service.py

@@ -0,0 +1,235 @@
+"""API Key validation service for remote-hosted mode."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("mcp-for-unity-server")
+
+
+@dataclass
+class ValidationResult:
+    """Result of an API key validation."""
+    valid: bool
+    user_id: str | None = None
+    metadata: dict[str, Any] | None = None
+    error: str | None = None
+    cacheable: bool = True
+
+
+class ApiKeyService:
+    """Service for validating API keys against an external auth endpoint.
+
+    Follows the class-level singleton pattern for global access by MCP tools.
+    """
+
+    _instance: "ApiKeyService | None" = None
+
+    # Request defaults (sensible hardening)
+    REQUEST_TIMEOUT: float = 5.0
+    MAX_RETRIES: int = 1
+
+    def __init__(
+        self,
+        validation_url: str,
+        cache_ttl: float = 300.0,
+        service_token_header: str | None = None,
+        service_token: str | None = None,
+    ):
+        """Initialize the API key service.
+
+        Args:
+            validation_url: External URL to validate API keys (POST with {"api_key": "..."})
+            cache_ttl: Cache TTL for validated keys in seconds (default: 300)
+            service_token_header: Optional header name for service authentication (e.g. "X-Service-Token")
+            service_token: Optional token value for service authentication
+        """
+        self._validation_url = validation_url
+        self._cache_ttl = cache_ttl
+        self._service_token_header = service_token_header
+        self._service_token = service_token
+        # Cache: api_key -> (valid, user_id, metadata, expires_at)
+        self._cache: dict[str, tuple[bool, str |
+                                     None, dict[str, Any] | None, float]] = {}
+        self._cache_lock = asyncio.Lock()
+        ApiKeyService._instance = self
+
+    @classmethod
+    def get_instance(cls) -> "ApiKeyService":
+        """Get the singleton instance.
+
+        Raises:
+            RuntimeError: If the service has not been initialized.
+        """
+        if cls._instance is None:
+            raise RuntimeError("ApiKeyService not initialized")
+        return cls._instance
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """Check if the service has been initialized."""
+        return cls._instance is not None
+
+    async def validate(self, api_key: str) -> ValidationResult:
+        """Validate an API key.
+
+        Returns:
+            ValidationResult with valid=True and user_id if valid,
+            or valid=False with error message if invalid.
+        """
+        if not api_key:
+            return ValidationResult(valid=False, error="API key required")
+
+        # Check cache first
+        async with self._cache_lock:
+            cached = self._cache.get(api_key)
+            if cached is not None:
+                valid, user_id, metadata, expires_at = cached
+                if time.time() < expires_at:
+                    if valid:
+                        return ValidationResult(valid=True, user_id=user_id, metadata=metadata)
+                    else:
+                        return ValidationResult(valid=False, error="Invalid API key")
+                else:
+                    # Expired, remove from cache
+                    del self._cache[api_key]
+
+        # Call external validation URL
+        result = await self._validate_external(api_key)
+
+        # Only cache definitive results (valid keys and confirmed-invalid keys).
+        # Transient failures (auth service unavailable, timeouts, etc.) should
+        # not be cached to avoid locking out users during service outages.
+        if result.cacheable:
+            async with self._cache_lock:
+                expires_at = time.time() + self._cache_ttl
+                self._cache[api_key] = (
+                    result.valid,
+                    result.user_id,
+                    result.metadata,
+                    expires_at,
+                )
+
+        return result
+
+    async def _validate_external(self, api_key: str) -> ValidationResult:
+        """Call external validation endpoint.
+
+        Failure mode: fail closed (treat as invalid on errors).
+        """
+        # Redact API key from logs
+        redacted_key = f"{api_key[:4]}...{api_key[-4:]}" if len(
+            api_key) > 8 else "***"
+
+        for attempt in range(self.MAX_RETRIES + 1):
+            try:
+                async with httpx.AsyncClient(timeout=self.REQUEST_TIMEOUT) as client:
+                    # Build request headers
+                    headers = {"Content-Type": "application/json"}
+                    if self._service_token_header and self._service_token:
+                        headers[self._service_token_header] = self._service_token
+
+                    response = await client.post(
+                        self._validation_url,
+                        json={"api_key": api_key},
+                        headers=headers,
+                    )
+
+                    if response.status_code == 200:
+                        data = response.json()
+                        if data.get("valid"):
+                            return ValidationResult(
+                                valid=True,
+                                user_id=data.get("user_id"),
+                                metadata=data.get("metadata"),
+                            )
+                        else:
+                            return ValidationResult(
+                                valid=False,
+                                error=data.get("error", "Invalid API key"),
+                            )
+                    elif response.status_code == 401:
+                        return ValidationResult(valid=False, error="Invalid API key")
+                    else:
+                        logger.warning(
+                            "API key validation returned status %d for key %s",
+                            response.status_code,
+                            redacted_key,
+                        )
+                        # Fail closed but don't cache (transient service error)
+                        return ValidationResult(
+                            valid=False,
+                            error=f"Auth service error (status {response.status_code})",
+                            cacheable=False,
+                        )
+
+            except httpx.TimeoutException:
+                if attempt < self.MAX_RETRIES:
+                    logger.debug(
+                        "API key validation timeout for key %s, retrying...",
+                        redacted_key,
+                    )
+                    await asyncio.sleep(0.1 * (attempt + 1))
+                    continue
+                logger.warning(
+                    "API key validation timeout for key %s after %d attempts",
+                    redacted_key,
+                    attempt + 1,
+                )
+                return ValidationResult(
+                    valid=False,
+                    error="Auth service timeout",
+                    cacheable=False,
+                )
+            except httpx.RequestError as exc:
+                if attempt < self.MAX_RETRIES:
+                    logger.debug(
+                        "API key validation request error for key %s: %s, retrying...",
+                        redacted_key,
+                        exc,
+                    )
+                    await asyncio.sleep(0.1 * (attempt + 1))
+                    continue
+                logger.warning(
+                    "API key validation request error for key %s: %s",
+                    redacted_key,
+                    exc,
+                )
+                return ValidationResult(
+                    valid=False,
+                    error="Auth service unavailable",
+                    cacheable=False,
+                )
+            except Exception as exc:
+                logger.error(
+                    "Unexpected error validating API key %s: %s",
+                    redacted_key,
+                    exc,
+                )
+                return ValidationResult(
+                    valid=False,
+                    error="Auth service error",
+                    cacheable=False,
+                )
+
+        # Should not reach here, but fail closed
+        return ValidationResult(valid=False, error="Auth service error", cacheable=False)
+
+    async def invalidate_cache(self, api_key: str) -> None:
+        """Remove an API key from the cache."""
+        async with self._cache_lock:
+            self._cache.pop(api_key, None)
+
+    async def clear_cache(self) -> None:
+        """Clear all cached validations."""
+        async with self._cache_lock:
+            self._cache.clear()
+
+
+__all__ = ["ApiKeyService", "ValidationResult"]

services/resources/active_tool.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -44,4 +45,4 @@ async def get_active_tool(ctx: Context) -> ActiveToolResponse | MCPResponse:
         "get_active_tool",
         {}
     )
-    return ActiveToolResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, ActiveToolResponse)

services/resources/editor_state.py

@@ -5,12 +5,14 @@ from typing import Any
 from fastmcp import Context
 from pydantic import BaseModel
 
+from core.config import config
 from models import MCPResponse
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from services.state.external_changes_scanner import external_changes_scanner
 import transport.unity_transport as unity_transport
 from transport.legacy.unity_connection import async_send_command_with_retry
+from transport.plugin_hub import PluginHub
 
 
 class EditorStateUnity(BaseModel):
@@ -132,17 +134,15 @@ async def infer_single_instance_id(ctx: Context) -> str | None:
     """
     await ctx.info("If exactly one Unity instance is connected, return its Name@hash id.")
 
-    try:
-        transport = unity_transport._current_transport()
-    except Exception:
-        transport = None
+    transport = (config.transport_mode or "stdio").lower()
 
     if transport == "http":
         # HTTP/WebSocket transport: derive from PluginHub sessions.
         try:
-            from transport.plugin_hub import PluginHub
-
-            sessions_data = await PluginHub.get_sessions()
+            # In remote-hosted mode, filter sessions by user_id
+            user_id = ctx.get_state(
+                "user_id") if config.http_remote_hosted else None
+            sessions_data = await PluginHub.get_sessions(user_id=user_id)
             sessions = sessions_data.sessions if hasattr(
                 sessions_data, "sessions") else {}
             if isinstance(sessions, dict) and len(sessions) == 1:

services/resources/layers.py

@@ -1,6 +1,7 @@
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -26,4 +27,4 @@ async def get_layers(ctx: Context) -> LayersResponse | MCPResponse:
         "get_layers",
         {}
     )
-    return LayersResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, LayersResponse)

services/resources/menu_items.py

@@ -1,6 +1,7 @@
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -31,4 +32,4 @@ async def get_menu_items(ctx: Context) -> GetMenuItemsResponse | MCPResponse:
         "get_menu_items",
         params,
     )
-    return GetMenuItemsResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, GetMenuItemsResponse)

services/resources/prefab_stage.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -36,4 +37,4 @@ async def get_prefab_stage(ctx: Context) -> PrefabStageResponse | MCPResponse:
         "get_prefab_stage",
         {}
     )
-    return PrefabStageResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, PrefabStageResponse)

services/resources/project_info.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -36,4 +37,4 @@ async def get_project_info(ctx: Context) -> ProjectInfoResponse | MCPResponse:
         "get_project_info",
         {}
     )
-    return ProjectInfoResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, ProjectInfoResponse)

services/resources/selection.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -52,4 +53,4 @@ async def get_selection(ctx: Context) -> SelectionResponse | MCPResponse:
         "get_selection",
         {}
     )
-    return SelectionResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, SelectionResponse)

services/resources/tags.py

@@ -2,6 +2,7 @@ from pydantic import Field
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -27,4 +28,4 @@ async def get_tags(ctx: Context) -> TagsResponse | MCPResponse:
         "get_tags",
         {}
     )
-    return TagsResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, TagsResponse)