Self-Host Funplay Unity MCP on a Fixed Port

How the self-hosted Unity MCP workflow works

Funplay MCP for Unity is an open-source, MIT-licensed MCP server implemented as a Unity Editor package. It runs alongside the Unity project currently open in the Editor. A compatible local AI client connects to the package through an HTTP endpoint in the form http://127.0.0.1:<port>/. The MCP Server window displays the address that the server actually bound.

This architecture is important because the service belongs to an active editor session. It is not a standalone production web application, a Unity game server, or a runtime component for a built player. The Unity Editor must be running, the correct project must be open, package compilation must have completed, and the MCP server must be enabled. Closing Unity or disabling the server makes that project's endpoint unavailable.

New projects normally receive a deterministic per-project port derived from the normalized project path. The current multi-project documentation maps this derived value into the range 20000 through 29999. Because the derivation is stable for a particular project path, a client configuration can continue using the same endpoint across normal Editor restarts. Different project paths normally produce different ports, which allows several Unity projects to host separate MCP servers at the same time.

This tutorial uses a manually pinned port. Pinning is useful when another component needs an explicit and predictable target, such as a Localtonet HTTP tunnel, a firewall rule, a CI environment, or a manually maintained MCP client entry. There is no universal example port that is guaranteed to be free on every host. Select an appropriate port for your own machine and confirm that another process does not already own it.

The canonical package instructions are maintained in the current Funplay MCP for Unity README. Port derivation, fallback handling, entry naming, upgrades, and concurrent Editor behavior are documented in the Funplay multi-project setup guide. Check those pages when upgrading because package versions and editor labels can change.

Prerequisites and decisions to make first

The current Funplay documentation requires Unity 2022.3 or later and the com.unity.nuget.newtonsoft-json package. Open the intended project with a supported Editor version and make sure Unity Package Manager can resolve dependencies. Installation and package compilation must finish without blocking errors before the MCP server can start.

You also need an HTTP-capable MCP client. The current project documentation lists compatibility with clients such as Claude Code, Claude Desktop, Cursor, Kimi Code, LM Studio, Windsurf, Codex, VS Code Copilot, and other MCP clients. Client configuration schemas and storage locations differ, so Funplay's built-in one-click configuration should be your first choice for local use.

A remote test additionally requires the Localtonet client on the same computer as Unity. The topology in this tutorial deliberately uses the same host because Funplay documents a listener on 127.0.0.1. Loopback is reachable only from the machine that owns it. Running Localtonet on another device would make that device's 127.0.0.1 refer to itself rather than the Unity computer.

Prepare these items

• A Unity project opened in Unity 2022.3 or later.
• Permission to add a package to that project.
• Working access to Unity Package Manager and the official Git repository.
• An available local port if you plan to pin one.
• A compatible MCP client for protocol-level verification.
• Version control or a current backup of the Unity project.
• The Localtonet client and a device-specific authentication token if controlled remote testing is required.
• Authorization from the project owner or organization before enabling any remote route.

Choose the right port behavior

Install the current Funplay MCP package

The primary documented installation method uses Unity Package Manager with the repository's Git URL. OpenUPM is an optional alternative when you want registry-backed version history and version selection. Use one source for the package. If a project already uses the Git dependency and you want to switch to OpenUPM, remove the Git dependency before adding the registry package.

Optional OpenUPM installation

If OpenUPM is already part of your Unity workflow, the currently documented CLI command is:

openupm add com.gamebooom.unity.mcp

The current official README documents package version 0.6.9 in its manual OpenUPM manifest example:

{
  "scopedRegistries": [
    {
      "name": "OpenUPM",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.gamebooom"
      ]
    }
  ],
  "dependencies": {
    "com.gamebooom.unity.mcp": "0.6.9"
  }
}

Version numbers are release-specific. Before copying the manifest into a project later, compare the dependency value with the current official README and choose the version your project has approved. Do not assume that 0.6.9 will remain the newest release indefinitely.

Account for version-dependent menu labels

This guide uses the current package documentation's main workflow labels: Funplay > MCP Server for server and port controls, Funplay > Tool Exposure for the exposed tool set, and Funplay > Plugin Settings for debug logging. Current repository pages are not fully consistent about the settings label, with the README also referring to MCP Settings. The execute-code safety toggle is documented in the MCP Server window for the current release documentation used here.

Start the MCP server and pin a fixed project port

Use the MCP Server window to select the port and start the service. The active URL displayed by this window is the source of truth. Do not reuse a remembered port from another project or assume that the requested port was successfully bound.

To restore automatic behavior, select Use Per-Project Port. That releases the pin and returns the project to path-derived selection. Direct HTTP and Experimental Broker Mode use the same port resolution rules, so toggling the transport mode does not itself require a different client URL.

Understand fallback behavior

A fallback is intentionally temporary. Funplay does not persist it because the conflict that caused it may disappear after a restart. The package remembers the fallback for the current Editor session, which can improve continuity during domain reloads, but one-click client configuration remains blocked while fallback is active.

That block is a safety measure. Writing the occupied stable port could send project-changing calls to the unrelated process that owns it. Writing the temporary fallback would create a client entry that can become invalid later. Resolve the conflict and return to a stable pinned or derived endpoint before configuring the client or tunnel.

Run several projects without port collisions

Each project in per-project mode receives its own derived port and client entry. The entry name begins with funplay- and is based on the project directory name. If two projects would produce the same entry name, the current multi-project behavior can append a short project hash instead of overwriting the existing entry.

A manually fixed port transfers collision management to you. Two active processes on the same host cannot listen on the same IP address and port combination. Give each concurrently open Unity project a distinct fixed port, or leave those projects in per-project mode. The current multi-project port guide explains the selection order, fallback state, entry naming, and upgrade behavior in detail.

Verify the local endpoint before considering remote access

Local verification must answer three separate questions: did Funplay bind the expected port, can an MCP client complete its protocol connection, and is that client connected to the intended Unity project? A generic browser request cannot answer all three.

Inspect the MCP Server window

Confirm that the server is enabled and that the displayed URL contains the pinned port. The window must not show an active fallback warning. If the reported value differs from the port you entered, do not update external configurations yet. Resolve the discrepancy first.

Do not use a browser as the definitive test

The address is an MCP HTTP endpoint, not a conventional web page. Opening it in a browser sends an ordinary HTTP request that may not represent a valid MCP exchange. An empty page, method error, protocol response, or other non-page result does not necessarily mean the server is broken. Conversely, receiving any HTTP response proves only that a process answered the port.

Use a compatible MCP client

Configure a supported client with the exact loopback URL shown by Unity. Restart or reload the client if its own workflow requires that step. Inspect its MCP connection state and available tools. For the first functional test, use discovery or a read-oriented operation instead of asking the client to create assets, alter scenes, generate scripts, install packages, enter Play Mode, or execute code.

Watch the intended Unity project during the test. The open project path, Funplay entry name, port, and client session should correspond. A different configured project can legitimately appear offline when its Editor is closed. Match the current entry and URL rather than assuming every disconnected funplay-* entry belongs to the active project.

Test restart stability

After the first successful session, disable or stop the MCP server, start it again, and confirm that the same pinned port returns. Reconnect the local client and repeat the non-destructive check. This validates the property required by a persistent tunnel configuration: the local target remains stable after a normal server restart.

Configure a local MCP client

Begin with One-Click MCP Configuration in Funplay > MCP Server. Select the intended client and choose Configure. This lets the package write the expected project entry instead of requiring you to guess a client-specific file path or schema.

For supported clients such as Claude Code, Cursor, Codex, OpenCode, and DeepSeek Harness, the current package also offers Configure + Skills. That option installs the built-in unity-mcp-workflow and unity-ui-composition project skills. Project Skills can also be opened from the Funplay menu.

If manual configuration is necessary, use the entry name and exact port displayed in the MCP Server window. A generic HTTP MCP entry can have this shape:

{
  "mcpServers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

This structure is not universal. Cursor examples may omit the type field, while VS Code uses a top-level servers object. LM Studio configuration locations can vary by platform and version, so its documented path is Program > Install > Edit mcp.json. Prefer Funplay's Configure function whenever it supports your selected client.

Keep local and remote entries distinct

A local client on the Unity computer should continue using 127.0.0.1. A client on another computer cannot use that address to reach Unity because its own loopback interface points back to the remote computer. If you perform an approved remote test later, use a separate entry name so the local and remote transport paths remain easy to distinguish:

{
  "mcpServers": {
    "funplay-<project>-remote-test": {
      "type": "http",
      "url": "<assigned-public-https-url>"
    }
  }
}

This is only a structural example. The remote entry must not be enabled merely because a tunnel URL exists. The security prerequisite described below still applies, and the exact schema must match the MCP client being used.

Use Localtonet only for controlled remote testing

An HTTP tunnel is the relevant Localtonet tunnel family because Funplay exposes an HTTP endpoint. Our client establishes an outbound connection to a Localtonet relay and forwards the assigned public HTTPS address to the selected local IP address and port. This does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.

The tunnel does not make Funplay independent of Unity. End-to-end access exists only while the correct Unity project is open, Funplay is enabled, the selected port remains active, the Localtonet client is connected, and the tunnel has been started.

For the current dashboard workflow and field descriptions, use the Localtonet HTTP tunnel documentation. Confirm current server choices, process-type availability, domain requirements, and plan-dependent options in the dashboard rather than relying on a copied configuration.

The Localtonet device token belongs only to the client-device connection. It is not an MCP bearer credential and must not be added to the remote MCP client. Similarly, possession of the public tunnel URL must not be treated as proof of authorization.

Understand the availability chain

Apply a strict security boundary

Funplay MCP is not merely a read-only project viewer. Its documented capabilities include scene and asset operations, script generation, prefab and UI workflows, screenshots, input simulation, Play Mode automation, package operations, editor-state access, and code-execution workflows. A connected client can therefore make substantial changes to the open project.

The package documents default-on checks for execute_code. These checks reject obvious destructive snippets, broad System.IO writes, raw file streams, and absolute, user, system, or traversal paths before compilation. The project explicitly describes this mechanism as a defensive guard rather than a complete sandbox. A trusted client can also pass safety_checks=false for an individual call.

These checks are valuable, but they are not caller authentication. Tool filtering, debug logging, transport encryption, URL secrecy, and code guards answer different security questions. None establishes who is permitted to connect to the endpoint.

Reduce exposed tools

Open Funplay > Tool Exposure and inspect the exact tools in the selected core or full profile. Enable only the capabilities required for the current task. If a workflow is limited to project inspection, avoid exposing mutation, package, Play Mode, input, filesystem, or code-execution capabilities simply for convenience.

Review safety and logging controls

For the current release documentation used here, review the execute-code safety controls in the MCP Server window. Use Funplay > Plugin Settings for debug logging. If your installed release instead displays MCP Settings, follow the matching documentation for that version. Keep safety checks enabled unless a reviewed local operation has a specific and justified need for an exception.

Debug logs can assist with troubleshooting, but logs may reveal project activity, endpoint details, error messages, paths, or tool inputs. Store and share them according to the project's confidentiality requirements.

Protect the project and host

• Commit or back up a known-good project state before enabling AI automation.
• Confirm the project folder, MCP entry name, and endpoint before every session.
• Use a dedicated project copy or controlled development environment for experimental prompts.
• Close unrelated confidential projects and assets.
• Review operations before allowing destructive scene, asset, package, filesystem, or code changes.
• Do not expose Localtonet tokens, repository credentials, registry credentials, or private endpoint details.
• Do not rely on a hard-to-guess tunnel address as access control.
• Stop the Localtonet tunnel immediately after a controlled test.
• Disable Funplay MCP when editor automation is no longer required.

Avoid an always-on public route

A continuously reachable tunnel is inappropriate when endpoint authorization has not been established. For an approved controlled test, start Unity first, verify the local endpoint, review the exposed tools, start the tunnel immediately before the test, supervise the session, and stop the tunnel immediately afterward. For ordinary work, use the local loopback endpoint only.

Routine operation and maintenance

Start a local work session

1. Open the intended Unity project.
2. Wait for package import and script compilation to finish.
3. Open Funplay > MCP Server.
4. Confirm the pinned port and make sure no fallback is active.
5. Enable MCP Server and verify the displayed loopback URL.
6. Connect the local MCP client.
7. Begin with a non-destructive discovery or read-oriented operation.

Add a controlled remote test only when approved

1. Confirm that the local workflow is healthy.
2. Review Tool Exposure and remove unnecessary capabilities.
3. Back up or commit the project state.
4. Confirm that the test is authorized and supervised.
5. Start the Localtonet client and the configured HTTP tunnel.
6. Use the assigned HTTPS address in the dedicated remote test entry.
7. Stop the tunnel immediately after the test.

End the session safely

1. Finish or cancel active MCP operations.
2. Save and review Unity project changes.
3. Stop the Localtonet tunnel if it was used.
4. Disable the Funplay MCP server when automation is no longer needed.
5. Wait for project writes and imports to finish before closing Unity.

Move or rename a project

A per-project port is derived from the normalized project path, so moving or renaming the project can change that derived port. A pinned port is intended to preserve the selected value. After a move, rename, package upgrade, or machine migration, inspect the MCP Server window and verify the actual endpoint before trusting an old client or tunnel configuration.

Upgrade the package

The current documentation says an existing project keeps the port it was already using by recording it as a pin. This helps preserve existing client entries. Even so, verify the endpoint, menu labels, tool exposure, and safety settings after an upgrade. If you want automatic path-derived behavior again, choose Use Per-Project Port.

OpenUPM users should check the current README before changing the manifest version. Git installations resolve the Git package and do not provide the same registry-backed Version History interface as OpenUPM.

Change transport mode

Direct HTTP is the default. Experimental Broker Mode is designed for stronger continuity across script recompilation and Play Mode domain reloads. Both use the same port resolution mechanism, so changing between them should preserve the endpoint. Because broker mode is experimental, test startup, reconnection, and domain reload behavior locally before using it during an important session.

Troubleshoot local and remote connection failures

The Funplay menu does not appear

Confirm that Unity Package Manager finished installing the package and that the project uses Unity 2022.3 or later. Review package-resolution and compilation errors. The server cannot be configured until the Editor loads the package and displays Funplay > MCP Server.

The settings menu has a different name

Current package documentation uses Plugin Settings for debug logging, while another current repository page refers to MCP Settings. Check the installed package version and use the visible menu that corresponds to that release. The central server and port workflow remains under Funplay > MCP Server.

The displayed port differs from the pinned value

Look for a fallback warning. The intended port may belong to another process. Do not point the MCP client or Localtonet at the occupied stable port. Stop the conflicting process when appropriate, select another available fixed port, or choose Use Per-Project Port. Wait for restart and use only the final displayed endpoint.

One-click configuration is disabled

Funplay intentionally blocks one-click configuration during fallback. A transient fallback should not be stored as a permanent client target, while the occupied stable port could route mutating calls to another process. Select Use Per-Project Port or Pin Current Port, wait for the restart, and configure the client only after the fallback state clears.

Another Funplay server appears offline

MCP clients can retain entries for several Unity projects. A project-specific entry is unreachable when that project's Editor is closed. Compare the entry name and URL with the current project's MCP Server window. Do not delete another project's entry merely because it is offline during this session.

The browser does not display a page

Funplay exposes an MCP HTTP endpoint rather than a normal website. A browser request does not perform MCP initialization. Test with a supported MCP client and compare its entry with the exact URL displayed in Unity.

The local endpoint works but the tunnel does not

Verify the chain in order. Confirm that the Localtonet client on the Unity computer is connected, the HTTP tunnel is started, and its target is 127.0.0.1 with the current pinned port. Then confirm that the remote test client uses the assigned public HTTPS URL rather than its own loopback address.

If Localtonet runs on another computer, its 127.0.0.1 refers to that other computer. The evidence used for this guide does not establish a supported non-loopback Funplay bind configuration, so move the Localtonet client to the Unity host rather than inventing a network-listener setting.

The public URL responds but MCP initialization fails

A generic HTTP response does not prove MCP compatibility. Compare the remote entry against a successful local configuration generated by Funplay. Check the client's HTTP transport support, configuration object name, URL, trailing slash, and reload requirements. Do not invent raw JSON-RPC requests as a substitute for the client's normal initialization.

Connections drop during script compilation

Direct in-process HTTP can be interrupted by compilation or domain reload activity. Test Experimental Broker Mode locally. It is intended to retain the same loopback port while improving continuity. Reverify the client connection before conducting another controlled tunnel test.

The wrong project receives a request

Stop the client and tunnel immediately. Check the Unity project folder, Funplay entry name, displayed port, and Localtonet target. This risk is especially important after a conflict or when several projects have manually assigned ports. Give each concurrent project a unique port and clear entry name.

The tunnel exists but is unavailable

Creating a Localtonet tunnel does not mean it is running. Confirm that Start was pressed, the selected client device is connected, Unity remains open, and Funplay MCP is enabled. End-to-end access also ends when the Localtonet client disconnects.

Frequently asked questions