Self-Host Funplay Unity MCP on a Fixed Port

How the self-hosted 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 that is currently open in the Editor. A compatible AI client connects to the package through an HTTP endpoint in the form http://127.0.0.1:<port>/. The exact address is displayed in the package's MCP Server window.

This architecture matters because the service is attached to an active editor session rather than deployed as an independent production web application. The Unity Editor must be running, the correct project must be open, and the MCP server must be enabled. Closing the Editor 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 documented derived range is 20000 through 29999. Because the derivation is stable for a given path, client configuration can continue to point to the same port after an Editor restart. Different project paths normally produce different ports, allowing several Unity projects to run their MCP servers at the same time.

This guide uses a pinned port instead. Pinning is useful when another component needs a predictable target, such as a firewall rule, a CI workflow, a manually maintained MCP configuration, or a Localtonet HTTP tunnel. The specific number must be chosen for the host environment and must not already belong to another process. The project documentation does not establish one universal fixed port that is safe on every machine, so we will not invent or prescribe one.

Prerequisites and decisions to make first

The documented minimum Unity version is Unity 2022.3 or later. The package also requires com.unity.nuget.newtonsoft-json. Before installation, open the intended Unity project with a supported Editor version and make sure the project can resolve packages through Unity Package Manager.

You also need an HTTP-capable MCP client. The project documents compatibility with clients including Claude Code, Claude Desktop, Cursor, Kimi Code, LM Studio, Windsurf, Codex, VS Code Copilot, and other MCP clients. Configuration formats and storage locations vary by client and version, so the package's built-in one-click configuration is the preferred local setup path.

For remote access, install and run the Localtonet client on the same computer as Unity, or on another device that can reach the Unity host's local endpoint. Using the same computer is the clearest arrangement when the service listens only on 127.0.0.1, because loopback addresses are reachable only from that host. The Localtonet client establishes an outbound connection to our relay, so inbound router port forwarding, a public IP address, firewall changes, and VPN setup are not required for the tunnel itself.

Prepare the following items

• A Unity project opened in Unity 2022.3 or later.
• Permission to add a package to that project.
• Access to Unity Package Manager and the Git repository URL.
• An available local port if you intend to pin one.
• A supported MCP client for functional verification.
• The Localtonet client and a device-specific authentication token for the later remote-access stage.
• Authorization from the project owner or organization before exposing editor automation outside the host.

Choose between a derived port and a pinned port

Install Funplay MCP for Unity

The primary documented installation method is Unity Package Manager using the package's Git URL. OpenUPM is an optional alternative for users who want registry-backed version history and version selection. Use one method for the dependency. If the project already has a Git-based installation and you want to switch to OpenUPM, remove the Git dependency before installing from the registry.

Optional OpenUPM installation

If OpenUPM is already part of your workflow, its documented CLI installation command is:

openupm add com.gamebooom.unity.mcp

Registry installation is useful when you want Unity Package Manager to display registry-backed version history and permit package version selection. A Git-installed package only shows the resolved Git version and does not receive the same registry-backed Version History list.

The documented manual OpenUPM configuration adds the OpenUPM scoped registry for com.gamebooom and then declares the package dependency. The following is the documented structure using version 0.6.5 from the supplied project evidence:

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

Start the MCP server and pin a fixed project port

Once the package is installed, use the MCP Server window to start the service and select its port. The window displays the exact URL the server actually bound. That displayed value, not a remembered value from another project, is the source of truth.

To return to automatic behavior later, click Use Per-Project Port. This releases the pin and restores path-derived selection. Both Direct HTTP and Experimental Broker Mode use the same port resolution rules, so switching transport modes does not by itself require a new endpoint or client entry.

What happens when several Unity projects are open

Each new project normally receives its own derived port and its own MCP 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 configuration process can append a short project hash rather than overwriting the existing entry.

A fixed port changes this responsibility. Two simultaneously running projects cannot both bind the same host port. Assign each concurrently active project a distinct fixed port, or leave them in per-project mode. Never point two Localtonet tunnels at what you believe are two projects when both configurations actually target the same port.

Verify the local HTTP endpoint before exposing it

Verification should answer three separate questions: did the server bind the expected port, can an MCP client establish the protocol connection, and is that client connected to the intended Unity project? A generic browser request answers none of these completely.

Check the server window

The MCP Server window should show the expected URL with your pinned port and no active fallback warning. The server must be enabled. If the port shown differs from the value you entered, stop and investigate before updating any external configuration.

Do not treat a browser page as the definitive test

The address is an MCP HTTP endpoint, not a conventional website. Opening it in a browser can issue a normal HTTP GET request that does not represent a valid MCP exchange. An empty page, protocol error, method error, or other non-page response therefore does not necessarily prove that the server is broken. Likewise, seeing any HTTP response proves only that something answered the port, not that the correct Unity project completed MCP initialization.

Use a real MCP client for functional verification

Configure a supported client with the exact loopback URL shown by Unity. Restart or reload the client if its documentation requires it, then inspect the client's MCP connection status and available tools. For the first functional check, use a non-destructive discovery or read-oriented operation provided by the client rather than asking the agent to create assets, edit scenes, generate scripts, or enter Play Mode.

Observe the intended Unity project while testing. The project identity, client entry name, endpoint port, and open Editor should all correspond. If several projects are registered, an offline entry belonging to another closed project can appear as a failed connection even while the current project's server is healthy. Match the entry name and URL before deleting or changing any configuration.

Verify restart stability

After the first successful connection, close or disable 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 needed by a persistent Localtonet tunnel: the local target does not unexpectedly move after a normal server restart.

Configure a local or remote MCP client

For local use, begin with One-Click MCP Configuration in Funplay > MCP Server. Select the intended client and click Configure. This lets the package write the recommended project entry instead of requiring you to guess a platform-specific file location.

For Claude Code, Cursor, Codex, OpenCode, and DeepSeek Harness, the 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 separately from the Funplay menu.

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

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

Some clients omit the type field, and VS Code uses a top-level servers object rather than mcpServers. Do not transfer one client's example blindly into another. Prefer the package's Configure function because it knows the supported format for its target.

LM Studio configuration locations can vary by platform and version. The documented approach is to use Program > Install > Edit mcp.json. Funplay's Configure action uses LM Studio's installation link and only updates an existing configuration file when one is already present, avoiding a guessed filesystem path.

Switching a client from local to remote

The local URL is appropriate while the client runs on the Unity computer. A client on another machine cannot use 127.0.0.1 to reach Unity because that address refers to the remote client's own loopback interface. After the Localtonet tunnel is running, create a separate client entry or carefully replace the URL with the public HTTPS address assigned to the tunnel:

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

Keeping distinct local and remote entry names can reduce confusion during testing. Exact configuration syntax still depends on the MCP client, and some clients may require a restart or a new session after their configuration changes.

Connect the verified endpoint through a Localtonet HTTP tunnel

A Localtonet HTTP tunnel is the appropriate tunnel family because Funplay exposes an HTTP service. The tunnel forwards requests from a public HTTPS address to the local IP address and fixed port selected in Unity. It does not convert Funplay into a standalone service, and it does not keep the MCP server alive when Unity is closed.

Our client establishes an outbound connection to a Localtonet relay server. This lets the service be reached without inbound router port forwarding, a public IP address, firewall changes, or VPN setup. The resulting tunnel is available only while the selected Localtonet client device remains connected and the tunnel is running.

The Localtonet target should remain the local loopback address and pinned port. The remote client should use only the public HTTPS URL supplied for the running tunnel. Do not place the Localtonet device token in the remote client's MCP configuration.

For current product-side guidance, consult our Localtonet documentation. Dashboard labels, plan availability, relay choices, and domain options should always be confirmed in the current interface.

Understand the complete availability chain

A successful remote session depends on every component in the chain: the Unity Editor is open, the correct project is loaded, Funplay MCP is enabled, the fixed port is available, the Localtonet client is connected, the HTTP tunnel is started, and the remote MCP client uses the current public address. If any component stops, end-to-end access stops.

Security guidance for privileged Unity automation

Funplay MCP is not 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 AI client may therefore be able to make extensive changes to the open project.

The project documentation describes default-on safety 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 documentation also explicitly describes this as a defensive guard rather than a complete sandbox. A trusted client can pass safety_checks=false for an individual call, so the guard must not be treated as endpoint authentication or full isolation.

Authentication or authorization for the Funplay MCP HTTP endpoint itself is not established by the supplied project evidence. A Localtonet HTTP tunnel gives the endpoint a public HTTPS address, but tunneling alone must not be interpreted as application-level authorization. Do not expose the service broadly unless you have an independently verified access-control design suitable for this privileged workload.

Reduce the exposed capability set

Open Funplay > Tool Exposure and review the exact tools provided by the selected core or full exposure profile. Enable only what the remote workflow actually requires. If the task is limited to inspection, do not expose mutation or execution capabilities merely for convenience.

Review Funplay's MCP settings before allowing remote access. Keep the documented execute_code safety checks enabled unless a carefully reviewed operation has a compelling need for an exception. Plugin debug logging can help during troubleshooting, but logs should be handled as potentially sensitive because they may reveal project activity or error details.

Protect the project and host

• Use version control and commit or back up a known-good project state before granting automation access.
• Close unrelated confidential assets and projects before the session.
• Confirm that the client entry maps to the intended project and port.
• Use a dedicated project copy or controlled development environment for untrusted or experimental prompts.
• Review proposed operations before allowing destructive scene, asset, package, filesystem, or code changes.
• Do not expose Localtonet authentication tokens, repository credentials, package registry secrets, or private endpoint details.
• Stop the Localtonet tunnel when the remote session ends.
• Disable the Funplay MCP server when editor automation is no longer required.

Prefer narrow exposure windows

For this use case, an always-on public tunnel is usually unnecessary. Start Unity and the local MCP server first, confirm the project and port, start the tunnel for the approved session, and stop it afterward. This reduces the time during which the endpoint is reachable and keeps the operational state easy to understand.

Routine operation and maintenance

Starting a work session

1. Open the intended Unity project.
2. Wait for package import and compilation to finish.
3. Open Funplay > MCP Server and confirm the pinned port.
4. Enable the MCP server and verify the displayed loopback URL.
5. Test the local MCP client with a non-destructive operation.
6. Start the Localtonet client and the existing HTTP tunnel only if remote access is required.
7. Connect the remote client to the tunnel's current public HTTPS URL.

Ending a work session

1. Finish or cancel active MCP operations.
2. Save and review Unity project changes.
3. Stop the Localtonet tunnel.
4. Disable the Funplay MCP server if it is no longer needed.
5. Close Unity after project writes and imports have completed.

Moving or renaming a project

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

Upgrading an existing project

The documented upgrade behavior preserves the port a project was already using by recording it as a pin. This helps existing client configurations continue to work. Even so, verify the endpoint after an upgrade, especially before remote exposure. If you want the project to coexist with other Editor instances using automatic path-derived ports, select Use Per-Project Port.

Changing transport mode

Direct HTTP is the default. Experimental Broker Mode is available for stronger continuity across Unity script recompiles and Play Mode domain reloads. Both modes use the same port selection mechanism and preserve the same client URL, so changing modes should not require the Localtonet tunnel target to change. Because broker mode is experimental, test project behavior and restart recovery before adopting it for important workflows.

Troubleshooting the local and remote connection

The Funplay menu does not appear

Confirm that Unity Package Manager completed installation and that the project meets the Unity 2022.3 or later requirement. Review Unity's package resolution and compilation errors. The server cannot be configured until the Editor successfully loads the package and displays Funplay > MCP Server.

The server displays a different port than the pinned value

Look for a fallback warning. The intended fixed port may already be occupied. Do not configure the MCP client or Localtonet against the occupied stable port. Stop the conflicting process if appropriate, choose a different available port, or return to Use Per-Project Port. Wait for the Funplay server to restart and use only the final displayed URL.

One-click configuration is disabled

One-click configuration is intentionally blocked while the server uses a fallback port. A transient fallback should not be written as a permanent client target, and the occupied stable port could route mutating calls to the wrong process. Choose Use Per-Project Port or Pin Current Port, allow the restart to finish, and then configure the client.

The local client reports another Funplay server as offline

Clients can retain entries for several Unity projects. A project-specific entry will be 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 the current session.

The local endpoint works but the public endpoint does not

Verify each layer in order. Confirm that the Localtonet client device is connected, the HTTP tunnel is started, and its local target is 127.0.0.1 with the currently pinned Funplay port. Then confirm that the remote MCP client uses the assigned public HTTPS URL rather than its own 127.0.0.1.

If the Localtonet client is not on the Unity computer, remember that 127.0.0.1 refers to the Localtonet client device itself. The supplied project evidence establishes Funplay's loopback endpoint but does not establish a supported non-loopback bind setting. For that reason, running our client directly on the Unity host is the documented-safe topology for this guide.

The public URL responds, but the MCP client cannot initialize

A generic HTTP response does not prove MCP protocol compatibility. Recheck the remote client's expected configuration schema, URL formatting, and HTTP transport support. Compare against a successful local entry generated by Funplay. Do not send invented JSON-RPC requests as a substitute for the client's normal initialization process.

Connections drop during script recompilation

Direct HTTP runs in process and may be interrupted by script recompilation or domain reload activity. Consider testing Experimental Broker Mode, which is intended to keep the same loopback port available with stronger continuity. If you enable it, reverify locally before resuming the public tunnel.

The wrong Unity project receives a request

Stop the remote session immediately. Check the Unity project folder, Funplay entry name, displayed port, and Localtonet local target. This problem is especially important after a port conflict or when several projects use manually assigned ports. Give each concurrent project a unique fixed port and a clearly distinguishable client entry.

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, and Unity's MCP server remains enabled. A tunnel also stops being available when the Localtonet client disconnects.

Frequently asked questions