Compatibility surface for an MCP server across 34 practitioner machines

Findings, ranked by participants affected

Three of these are blocking. None of them threw an exception you would have seen.

1. 01blocking11 of 34 participants

   Tool-name collision resolves to the wrong server, silently

   Environments with 3 or more MCP servers already registered

   What happened

   Two of the participants' existing servers expose a tool named search. The agent picked one of those instead of yours. No error, no log line — the run simply produced the wrong result and the participant assumed the tool was bad at its job.

   What the person did about it

   Four participants re-ran it and got a different answer each time and concluded it was non-deterministic. Two removed your server. One found it by reading the session transcript, and said they would not have looked if we had not asked.

   Suggested fix

   Namespace the tool, or declare the collision at registration and let the agent disambiguate.

2. 02blocking8 of 34 participants

   Quickstart has no Windows path

   Windows 11, PowerShell 7 and Git Bash

   What happened

   The documented install is a curl | sh one-liner. In PowerShell it fails on the pipe; in Git Bash it installs to a path the agent config does not look in.

   What the person did about it

   Three participants translated it themselves and succeeded in under fifteen minutes. Three tried WSL, which worked but put the binary somewhere the host agent could not reach. Two stopped.

   Suggested fix

   Ship a PowerShell path in the quickstart, and state which shell each line assumes.

3. 03blocking6 of 34 participants

   Node 18 fails a version check that never prints

   node 18.x, all operating systems

   What happened

   A dependency requires node ≥ 20. The failure surfaces as a stack trace the agent swallows, so the participant sees the tool register and then do nothing.

   What the person did about it

   Every one of the six assumed the tool was broken rather than their runtime. None checked their node version unprompted.

   Suggested fix

   Check the runtime version at startup and fail loudly with the required range.

4. 04friction5 of 34 participants

   Install assumes uv is present

   Linux, uv not installed

   What happened

   The install step shells out to uv with no check and no fallback to pip.

   What the person did about it

   Three installed uv and continued. Two did not have permission to and stopped there.

   Suggested fix

   Detect uv, fall back to pip, or state the prerequisite above the install block.

5. 05friction5 of 34 participants

   The config block does not say which file it goes in

   All environments

   What happened

   The JSON snippet in the README is correct but unlabeled. Participants pasted it into four different files across the cohort.

   What the person did about it

   Two read the snippet twice and guessed right. Three guessed wrong and spent an average of nine minutes before finding the correct file.

   Suggested fix

   Put the absolute path above the snippet, per platform.