Does updating the Unity package require updating the pinned mcpforunityserver version in the client config?

[DuyTaDinh]

Question

When I update the MCP for Unity package inside Unity, do I also have to update the pinned
Python server version in my MCP client config, and what happens if I don't?

My claude_desktop_config.json (generated by Window → MCP for Unity → Configure All Detected Clients)
contains an exact pin:

{
  "mcpServers": {
    "unityMCP": {
      "command": "C:\\Users\\<me>\\.local\\bin\\uvx.exe",
      "args": [
        "--from",
        "mcpforunityserver==10.1.2",
        "mcp-for-unity",
        "--transport",
        "stdio"
      ],
      "type": "stdio"
    }
  }
}

The Unity window currently reports v10.1.2, Transport Stdio, port 6400, session active — so
right now the two match. My concern is what happens after the next package update.

Specifically:

1. Is the pin authoritative, or is it just a snapshot? i.e. after I bump the Unity package
   (e.g. 10.1.2 → 10.2.0), must I re-run Configure All Detected Clients (or hand-edit the JSON)
   so the pin follows, or does the package pick the right server version some other way?
2. What breaks on a mismatch? If the Unity package is newer than the pinned server, do I get
   a hard failure (handshake refused / "server version mismatch"), silently missing tools, or
   is it fine as long as major versions agree? Is there a documented compatibility policy
   (e.g. server and package share the same major/minor)?
3. Should the pin be exact at all? Would something like mcpforunityserver>=10.1,<11 or
   an unpinned mcpforunityserver be a supported setup, or does the project intentionally
   generate an exact == pin (reproducibility, avoiding uvx pulling an untested server)?
4. Is there a way to detect drift from the Unity side? The Connect tab shows the package
   version — could/does it also surface the running server version so a mismatch is visible
   before things break?

Our project tracks the package from git rather than a fixed tag:

"com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main"

So the Unity side can move forward on any Packages/packages-lock.json refresh while the client
config keeps pointing at ==10.1.2. On a small team this drift is easy to miss — one dev
re-resolves packages, another doesn't touch their config, and only one of them has a working
session.

[rakeshutekar]

On the core question — the pin is a snapshot, not something that follows the package. uvx --from mcpforunityserver==10.1.2 is an exact version specifier: uvx resolves and runs exactly 10.1.2 in its ephemeral environment, with no awareness of what version the Unity package is on. So when you bump the Unity package 10.1.2 → 10.2.0, nothing about that ==10.1.2 line changes on its own — you keep launching the old server until you either re-run Window → MCP for Unity → Configure All Detected Clients (which regenerates the JSON with the now-current version) or hand-edit the pin.

That's exactly the drift you're worried about, and your git-tracked package setup (#main) makes it sharper: a packages-lock.json refresh can move one dev's Unity side forward while their claude_desktop_config.json still says ==10.1.2, silently. Re-running Configure is per-machine, so it won't propagate to teammates automatically.

A couple of practical takes on your sub-questions:

• Should the pin be exact at all? For a team on a moving #main, an exact == is the fragile choice precisely because it can't follow. If the maintainers' compatibility story allows it, a range like mcpforunityserver>=10.1,<11 would let uvx pull a compatible server automatically and cut the manual re-Configure step — at the cost of reproducibility (uvx could fetch a server you haven't tested). Unpinned (mcpforunityserver, latest) maximizes "always matches" but minimizes reproducibility. The project generating an exact == is the reproducible-by-default choice, which is reasonable, but it puts the drift burden on you.
• Tip to make drift visible now: since uvx --from mcpforunityserver==X is just a normal uv invocation, you can check what the config would pin to vs. what's installed without touching Unity — e.g. compare the == in the JSON against the package version the Connect tab reports. If they diverge, you're drifting.

I'd flag the rest as genuinely maintainer questions, since they depend on the project's intended contract rather than anything observable from the config: (a) the exact failure mode on a server-newer-than-package or package-newer-than-server mismatch (hard handshake error vs. silently missing tools), (b) whether there's a documented same-major/minor compatibility policy, and (c) whether the Connect tab could surface the running server version next to the package version to make drift visible before it breaks — that last one sounds like a worthwhile feature request. Worth pinning a maintainer for a definitive statement on the compatibility policy, because that determines whether a version range is safe for your team.

[RizgarOzan]

Some of this is handled by the package already. From the code on main:

1. The pin follows the package on its own, once per machine. StdIoVersionMigration (MCPForUnity/Editor/Migrations/StdIoVersionMigration.cs) is [InitializeOnLoad]. On the first editor load after the package version changes, it rewrites the config of every auto-configurable client that has a stdio unityMCP entry, so ==10.1.2 becomes the new version. Claude Code gets re-registered through the CLI. It records the last version it handled in EditorPrefs. That makes it per machine: a teammate's config is updated the next time they open Unity with the new package. It's skipped in batch mode, and when a rewrite fails it logs a warning and tries again next session.

2. Mismatches are visible in the window. If the pin in a client config differs from what the package expects, that client's status is Version Mismatch with "Server version doesn't match the plugin. Re-configure to update." (McpClientConfiguratorBase.CheckStatus), and the Connect section shows a warning banner for it. Stable/prerelease mixes get their own message.

3. The exact pin is intentional. AssetPathUtility.GetMcpServerPackageSource() returns mcpforunityserver=={package version} for stable builds. It falls back to mcpforunityserver>=0.0.0a0 (with --prerelease explicit) only for prerelease package versions, because a semver -beta.N isn't a valid PEP 440 pin. To run something else, set Advanced → server source override (a git URL, a local path or another --from value). The configs are then generated from the override and compared against it. A hand-edited range in the JSON is reported as a mismatch, and the migration step replaces it on the next package bump.

4. What breaks if they drift. I found no package↔server version handshake. The plugin registers with project name/hash and the Unity editor version only (Server/src/transport/models.py, RegisterMessage). So the server doesn't refuse a mismatched plugin up front. Problems show up per call: a tool the server knows but the plugin doesn't comes back as Unknown or unsupported command type: <name> (CommandRegistry.cs), and changed parameters fail inside the tool. I didn't find a documented compatibility policy. The generated configs keep server and package at the same version.

With #main tracked from git, open Unity once after re-resolving packages and check the client list for "Version Mismatch" before starting a session.

[MohammediYunus]

For your team's #main setup, there is one additional case to watch: the automatic migration uses the version in package.json, not the Git commit. It skips rewriting configs when that version is unchanged. If a package refresh moves to another commit with the same package version, that alone will not refresh the server pin.

I'd pin the Unity dependency to a tested release tag and keep the exact server pin, then update them together. The stable server source is generated from the package version, so replacing the pin with a range would not establish a match to arbitrary commits on main.

Also, the Version Mismatch check compares the configured source string, rather than querying the running server process. After updating the generated config, restart the MCP client so it launches the server from that config.

[RizgarOzan]

Good catch, thanks. I checked it at aa5fc63: the migration compares against the package.json version (StdIoVersionMigration.cs L35-46), so a different commit with the same version won't refresh the pin. Pinning a tagged release and bumping the server pin together, as you suggest, is the safe setup for a #main team.

[RizgarOzan]

Thanks, I checked this in the code (aa5fc63). You're right about the gate. StdIoVersionMigration.cs returns early when EditorPrefs already has the current package.json version (EditorPrefKeys.LastStdIoUpgradeVersion). So a git install that keeps the same version won't rewrite the configs again. Bumping the version, or clearing that EditorPrefs key, forces the run. Good catch for the #main setup.