Making an MCP Server Install Itself: Three Hosts, Three Mechanisms, Gotchas

MCP server setup still often means hand-editing a JSON file — and every host uses a different file and format. That friction keeps developers from running servers they'd otherwise use. This post breaks down three hosts, their installation mechanisms, and the gotchas that trip you up.

Three Hosts, Three Mechanisms

• VS Code: Has a real API — registerMcpServerDefinitionProvider. Declare a provider in package.json and return the server definition at runtime. VS Code shows a consent prompt. No config file editing. Cleanest, but requires shipping a VS Code extension.
• Cursor: No native API. Write .cursor/mcp.json directly with root key mcpServers.
• Claude Code: Use the CLI. Do not hand-write the file. Run e.g.:
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

Six Gotchas to Guard Against

1. That JSON file isn't yours. Cursor's mcp.json holds the user's other servers. Read, merge your entry, preserve unrelated keys — don't overwrite.
2. Survive a malformed file. If the file exists but is invalid JSON, do not treat it as empty and overwrite. Same for read/permission errors — rethrow. Treating “couldn't read it” as “nothing there” will corrupt configurations.
3. Back up + write atomically. Copy the existing file before touching it, write to a temp file, then rename over the target. A half-written mcp.json breaks the editor.
4. Installing twice must be a no-op, not an error. The Claude CLI errors if the entry already exists — so remove then add. For file hosts, key by server name and replace in place. Re-running should converge, not duplicate.
5. Scope changes everything. User-level vs project-level install changes where the config lands and what the server needs (e.g., explicit data dir vs. upward-discovery). Pick deliberately.
6. You own staying current. The version registered drifts from what you ship. Add a check: “is what's installed still the version I bundle?” and a clean re-install path. One button shows state: install, update, or up to date.

The meta-lesson: hand-setup fails because a human pasting a snippet doesn't know the absolute path, the right scope, env vars, or how to merge safely. The install code does.