Settings¶

Open MCP > Settings to configure the Unity-side server and the in-Unity Chat experience.

Ports¶

• Port is the Unity MCP transport port. The default is 9500.
• Chat Port is the Unity-side MCP transport reserved for in-Unity Chat. The default is 9501; the Python relay uses a separate dynamically selected local port.
• The two ports must differ and must be between 1024 and 65535.

Changes are saved immediately, but the MCP server must restart before new ports take effect. A Restart Server button appears in the port settings after you change either port; select it to restart right away. Alternatively, open MCP > Status and select Restart, then reconnect external clients.

Port discovery normally removes the need to put a fixed port in client configuration. Keep a fixed port only when your environment requires one.

Code Execution Security¶

Security Level controls the scan applied by the execute_code tool. It is not a global sandbox for every MCP tool.

Allow All is the current default. Use it only for trusted prompts and projects.

Tools and Permissions¶

These pages control different layers:

Disabling a Unity-backed handler on the Tools page blocks its dispatch from both external clients and MCP Chat after reconnect. For Python-only tools, capability gating controls advertised visibility rather than a separate Unity dispatch authorization. The Permissions page stores a separate Chat-only deny-set and does not change external-client visibility. See the security policy for the distinction between these layers.

The current relay start request does not forward that deny-set to CLI backends. Until it does, use Tools when a restriction must be enforced by the Unity MCP server; treat Permissions as saved Chat policy rather than a security boundary.

Use the Minimal, Full, and No visuals presets as starting points, then adjust individual categories. Use Allow All or Deny All on the Permissions page only when you intend to change the complete Chat deny-set.

Plugins¶

The Plugins page appears when at least one registered plugin contributes a settings UI. Open a plugin card to load its controls. Plugin tools also appear under the Plugins group on the Tools page.

If a plugin has no settings UI, it does not create a Plugins card. Its tools can still be available through the live tool catalog.

LLM Sampling¶

LLM Sampling stores profiles for optional summarization, intent, and visual analysis. It does not change the backend selected in MCP Chat.

Each task has its own foldout with Backend, Model, Max Turns, and Timeout controls. Claude Fast, Gemini Flash, and Codex apply one preset to every task. Screenshot-dependent entries are disabled while the screenshot tool is disabled.

The NL Composer row is Editor-side and uses its saved CLI profile directly. The other rows target the Python sampling service, which currently executes Claude CLI profiles only. For those server-side rows, a Codex or Gemini selection fails closed when the task runs; it does not silently fall back to Claude. Server-side sampling also requires the MCP server process to start with UNITY_MCP_VISUAL_VERIFY=1 and the Claude CLI to be installed and authenticated.

The Editor stores this page in Library/MCP_LlmConfig.json. NL Composer reads its row from that file, but the Editor does not currently push the other saved profiles into the Python server. To override a live server profile, enable the SYSTEM tools and call, for example:

set_llm_config(config="visual_verify:haiku,2,15,0,claude")

That override is process-local and is lost when the MCP server restarts. For server-side rows, treat the Codex and Gemini preset values as stored configuration for future provider support, not as available sampling backends in this release.

Chat Settings¶

The Chat Settings page owns:

• auto-scroll and inactivity timeout
• CLI binary discovery status
• cached CLI authentication status for Claude
• per-backend model selection and stored launch options
• context-chip visibility and colors
• settings contributed by Chat extensions

Authentication happens in each backend CLI. Unity Biome MCP does not provide an API-key field. Install and sign in to the CLI first, ensure its executable is available on the login-shell PATH, then restart Unity.

Chat currently applies the selected model at launch. Stored binary overrides, permission options, startup timeouts, and extra arguments are saved but are not applied when the relay starts.

See Using MCP Chat for the task workflow and Chat Backends for process and session behavior.

Updates and Rollback¶

Update¶

1. Open MCP > Settings > Updates.
2. Select Check for Updates.
3. Select Level Up! to play the release animation.
4. Optionally select See new stats to review the release summary.
5. Select Update now.

For UPM installations, the updater installs the selected package release and refreshes the generated project server pin after Unity reloads. Local source checkouts use their local update flow.

Roll back or repair a version mismatch (UPM installations)¶

1. Open MCP > Settings > Version Picker.
2. Select a release.
3. Choose Roll Back to install it.
4. If the plugin and server pin differ, choose Align Both.

Unity reloads assemblies during a package change. Wait for compilation to finish before reconnecting clients.

Version Picker installs a UPM package version. For a local source checkout, use the checkout's normal source-control update or rollback flow instead.

Recovery¶