How to Sync MCP Servers Across Machines in Claude Code

You add an MCP server on the office Mac with claude mcp add. On the travel laptop the same project opens, and the tools are gone. MCP configuration is scoped and stored in files Claude Code manages for you — it is not a cloud preference that follows your Anthropic login. If you work on more than one machine, you need a plan for how to sync MCP servers across machines.

Where Claude Code stores MCP config

Claude Code uses three scopes. Knowing which file each one writes is half the battle:

Official docs: Connect to MCP servers. Project scope is already a sync mechanism for teams — commit .mcp.json and teammates inherit the definitions. The multi-machine problem is almost always user and local scope: personal servers that never leave the laptop where you typed claude mcp add.

What you should never sync

MCP definitions often embed connection strings, tokens, or absolute paths. Syncing blindly is how people paste a production database URL into a gist "for convenience."

Leave on each machine:

• Auth tokens and OAuth state for remote MCP connectors
• Machine-specific paths (/Users/alice/... vs /home/bob/...)
• Anything in session/cache directories under ~/.claude/

Sync the shape of the server (command, args, URL template) and re-authenticate on each machine when the server requires it.

Approach A: project .mcp.json for shared tools

If the server is something the project needs — a docs searcher, a repo-aware browser tool, an internal API — add it at project scope:

claude mcp add --scope project <name> -- <command and args>

Commit .mcp.json. On another machine, clone, open the project, approve the server when Claude Code prompts, and run /mcp to confirm it connected.

This does not help personal utilities you want in every repo (a calendar MCP, a notes MCP). Those belong at user scope, which is per-machine until you sync it.

Approach B: export / import a manifest

Several open-source tools treat MCP (and sometimes plugins) as a declarative manifest you can version:

• Export live servers from ~/.claude.json into a portable JSON
• Import on the other machine so the CLI re-registers them
• Optionally pair with chezmoi so the manifest rides with your dotfiles

This is a good fit if you already live in git and want a diffable source of truth. You still run import after every change, and you still fix machine-specific args by hand.

Approach C: git sync of allowlisted config

Reddit threads on r/ClaudeCode and r/ClaudeAI repeat the same recipe: private repo, allowlist portable files, exclude credentials and session data, symlink or bootstrap on each box. For MCP specifically, people either:

• keep a script of claude mcp add ... commands and re-run it on each machine, or
• merge mcpServers into ~/.claude.json with a tool that upserts without wiping hand-added entries

Scripts age poorly when a server's package name or flags change. Upserting JSON is better, but only if you never commit secrets.

Approach D: a background agent that writes MCP in the right format

Copying JSON assumes every machine runs the same harness the same way. In practice you may have Claude Code on one box, Cursor on another, and Codex on a VM — each wants MCP entries in its own config shape.

loadout installs and toggles MCP servers from one dashboard. A background agent on each paired machine writes the entry in the format that machine's detected coding tools expect. You are not maintaining three JSON dialects by hand. Skills can ride the same path; see sync Claude Code skills across machines and how syncing works.

Project .mcp.json is for teammates. User-scope sync is for your fleet. Mixing the two is how personal tokens end up in a shared repo.

Practical sequence

1. List what you have: run /mcp on the machine that is "ahead."
2. Split the list into project-shared vs personal.
3. Move project-shared servers into .mcp.json and commit.
4. For personal servers, pick manifest import, an allowlisted git sync, or loadout — and strip secrets from anything that will be committed.
5. On the second machine, import or pair, then re-auth any remote connectors.
6. Confirm with /mcp on both machines against the same test project.

FAQ

Does signing into Claude sync my MCP servers?

No. MCP registration is local configuration. Account login does not replicate ~/.claude.json across devices.

Should I put API keys in .mcp.json?

Avoid it. Prefer env vars the server reads at runtime, a secrets manager, or per-machine auth. If a key must appear in config, keep that server at user/local scope and out of git.

User scope or local scope for a personal server?

User scope if you want it in every project on that machine. Local scope if it is an experiment tied to one repo. Neither crosses machines without a sync step.

Can I sync MCP the same way I sync skills?

Same idea (portable vs machine-local), different files. Skills are folders; MCP is JSON registration plus optional binaries. A tool that only copies ~/.claude/skills/ will not register MCP servers for you.