Open Source · MCP · Architecture · 12 min read

It started with a missing comma.

We had just added a new tool to our MCP server stack and needed to push the update across our editors. Claude Desktop first, then Cursor, then Windsurf. Three editors, three config files, each with their own format quirks. We were moving fast, copy-pasting JSON blocks between files, and somewhere in the Windsurf config we dropped a comma between two properties. The file broke silently. No error message. No warning. The MCP server just stopped loading, and the AI had no tools and no explanation as to why.

We found the bug twenty minutes later. Fixed it, moved on. Then two weeks after that, we rotated an API key and had to do the whole thing again. Five files this time. Claude Desktop, Cursor, Windsurf, VS Code, Claude Code. Each one formatted differently. Each one with its own location buried somewhere in a different system path. Each one perfectly capable of failing without telling you anything useful.

After the third or fourth time this happened, we stopped and asked an honest question: why does this problem exist?

The Model Context Protocol was designed to unify AI tooling. The whole premise is that any MCP-compatible editor can connect to any MCP server through a standard interface. And that promise largely holds on the server side. But on the configuration side, the ecosystem had quietly fragmented into a mess of incompatible JSON formats, inconsistent key names, and editor-specific quirks that developers had to memorize or rediscover every single time they set up a new machine or added a new tool.

Claude Desktop uses mcpServers. VS Code uses servers. Windsurf uses mcpServers at the top level but insists on calling SSE endpoints serverUrl instead of url. Cursor supports both global and project-level configs. Claude Code shares the Claude Desktop format but lives in a completely different hidden directory. None of them talk to each other. None of them know what the others have. The moment you add a server to one editor, every other editor falls behind, and there is no automated way to tell.

The deeper problem is structural. Every mature part of the developer stack solved this problem years ago. Git has .gitignore. Docker has docker-compose.yml. Node has package.json. These files exist because the ecosystem recognized that distributed configuration without a source of truth is a maintenance nightmare. MCP arrived without one, and developers are paying the price every time they switch editors or rotate a credential or onboard a new machine.

We built mcp-sync because we got tired of paying that price ourselves. We were building Vektor Slipstream, a 42-tool MCP server for persistent agent memory, and every release cycle involved manually touching five config files in five different formats. Getting any one of them wrong meant an agent with no tools and no way to know why. So we stopped and built the infrastructure layer that should have shipped with the protocol.

The concept is simple. One .mcp.json file holds your server definitions. Three commands handle everything else.

mcp-sync export # pull from all editors into .mcp.json
mcp-sync diff # show what has drifted
mcp-sync sync # push .mcp.json to all editors

How It Works
The first thing we learned building the connectors is that reading and writing JSON is the easy part. The hard part is doing it without breaking anything the editor already has.

Every editor config file contains more than just MCP server definitions. Claude Desktop has a user preferences block that controls sidebar behavior and scheduled tasks. Cursor stores internal project settings alongside the server list. VS Code mixes workspace configuration with the MCP entries. A naive approach that reads the server list and writes it back would silently wipe all of that context. Users would lose settings they had carefully configured and have no idea why.

Every connector in mcp-sync solves this with a strict merge pattern. We read the entire existing file first, extract only the MCP server block, merge in the incoming changes, and write the whole thing back with everything else untouched.

let existing = JSON.parse(readFileSync(cfgPath));
const updated = {
...existing,
mcpServers: { ...existing.mcpServers, ...incoming }
};
writeFileSync(cfgPath, JSON.stringify(updated, null, 2));

Incoming servers win on conflict. Everything else survives unchanged. This means you can run mcp-sync sync on a machine that already has a partially configured editor and trust that the sync will add what is missing without destroying what is already working.

The format translation layer sits inside each connector individually. The Windsurf connector, for example, converts url to serverUrl on the way in and reverses the translation on the way out. The VS Code connector handles the fact that the top-level key is servers instead of mcpServers. Each connector is self-contained and ships no shared runtime dependencies, which means you can read any one of them in isolation and understand exactly what it does.

The Vault
The moment we had sync working, the next problem became obvious. Config files contain secrets. API keys, licence keys, authentication tokens. The whole point of .mcp.json is that you define your servers once and potentially commit the file to version control. But committing secrets to a repository is how credentials end up on breach notification services.

We built a local encrypted vault into mcp-sync to solve this cleanly. It uses AES-256-GCM encryption, derives its key from your machine's hostname and a locally stored random salt, and stores everything in ~/.mcp-sync/vault.json. No cloud. No account. Nothing leaves your machine.

The workflow is straightforward. You store a secret once:

mcp-sync vault set my-api-key sk-abc123
Then reference it in .mcp.json using a vault prefix:

"env": { "API_KEY": "vault:my-api-key" }

At sync time, the tool walks the server configuration and replaces every vault reference with the decrypted value before writing to any editor. The editor gets the real working key. The .mcp.json you commit to Git contains only the reference string, which is useless without the local vault.

The machine-binding is intentional. The encryption key is derived from your hostname combined with a salt that only exists on your local drive. Secrets encrypted on your desktop cannot be decrypted on your laptop. This makes the vault unsuitable as a backup mechanism, but that is fine because backup is not what it is for. It is a secrets-at-rest layer for your local workflow, and in that role it works exactly as needed.

One practical note: secrets with spaces work correctly. mcp-sync vault set my-key hello world stores hello world as a single value. The argument parser joins everything after the key name, so you do not need to worry about quoting behavior across different shells.

The Diff Problem
The diff command is where most of the interesting engineering lives. The goal is to compare what is in .mcp.json against what each editor actually has configured, and report any meaningful differences. Simple in theory. Surprisingly subtle in practice.

Download the Medium App
The naive approach is to stringify both sides and compare the strings. This breaks immediately for several reasons. First, editors inject extra fields during normal operation. The Claude Desktop connector adds transport: "stdio" and a clients array. Windsurf normalizes serverUrl back to url when you export from it. Second, vault references in .mcp.json never match the resolved plain-text values in the editor configs. Third, key ordering in JSON objects varies between editors and can change between writes.

The solution is canonical comparison. Instead of comparing the raw objects, we extract only the fields that actually determine behavior and compare those.

const CANONICAL = ['command', 'args', 'url', 'headers'];
function canonical(cfg) {
const out = {};
for (const k of CANONICAL) {
if (cfg[k] !== undefined) out[k] = cfg[k];
}
out.__envKeys = Object.keys(cfg.env ?? {}).sort().join(',');
return JSON.stringify(out);
}

We compare command, args, url, and headers directly. For environment variables, we compare only the key names in sorted order, not the values. A vault reference on one side and a resolved plain-text value on the other both produce the same canonical signature as long as the variable names match. This means diff tells you about genuine structural differences rather than noise from how different connectors represent the same underlying configuration.

The diff command exits non-zero when it detects drift, which makes it composable with CI pipelines:

• name: Check MCP config drift run: mcp-sync diff

For teams running shared agent infrastructure, this is the difference between hoping that everyone’s configs are aligned and actually verifying it on every commit.

The VS Code Scoping Question
VS Code handles MCP configuration differently from every other editor in the support matrix, and it is worth explaining clearly because it trips people up.

VS Code MCP servers are workspace-scoped. There is no global config file. Servers live in .vscode/mcp.json inside your project directory. This means running mcp-sync sync from your home directory has no effect on VS Code at all. You need to run it from inside a project for it to write anything useful.

We considered adding detection logic that would warn users when they run sync outside a VS Code workspace. We decided against it because the scoping is actually a feature. VS Code’s model acknowledges that different projects need different MCP servers, and mcp-sync respects that. Run the sync command from inside the project where you want the servers, and everything works as expected.

The Vektor Connection
Everything described above solves a general problem. Any MCP user with more than one editor benefits from a single source of truth for their server configuration. But there is a specific scenario where config drift causes damage that goes beyond missing tools and wasted time.

That scenario is persistent agent memory.

Vektor Slipstream is a 42-tool MCP server that gives AI editors access to a persistent memory layer. When Claude stores something in Vektor, it is available the next session, the next week, and across every editor that has access to the same server. Recall, graph traversal, automated briefings, pattern recognition across long timelines. The entire value proposition depends on every editor in your workflow pointing at the same running instance.

Config drift breaks this in ways that are genuinely hard to debug. An agent in Cursor with no Vektor connection has no access to what Claude Desktop stored yesterday. An agent in Windsurf pointing at a stale binary path has no tools at all and no error message explaining why. You end up in a situation where some editors have memory and others do not, and the inconsistency produces agent behavior that is confusing and difficult to reproduce.

mcp-sync makes this a one-time configuration problem rather than a recurring maintenance task.

npm install -g vektor-slipstream
vektor activate YOUR-LICENCE-KEY
mcp-sync vault set vektor-licence-key YOUR-LICENCE-KEY
mcp-sync export
mcp-sync sync

Four commands. Every editor on your machine now runs the same Vektor instance with the same configuration. When you update Vektor, you update one path in .mcp.json and run sync again. The licence key stays in the vault and never touches a config file that could be committed or shared.

The result is that memory becomes genuinely portable across your entire workflow. Claude can recall an architectural conversation you had in Cursor three days ago. Windsurf can pick up business context that Claude Code stored last week. The memory graph is consistent because the server is consistent, and the server is consistent because the configuration has a single authoritative source.

What Comes Next

mcp-sync is open source, MIT licensed, and requires no account to use. The vault works completely standalone. You do not need Vektor to benefit from encrypted local secret storage and synchronized editor configs.

The roadmap for the next release includes a --watch flag that runs fs.watch on .mcp.json and automatically syncs to all editors when the file changes. After that, connectors for Cline and Roo Code. The architecture makes adding new editors straightforward: one self-contained file, four methods, done.

If you are running Vektor, mcp-sync is the piece that makes your memory server genuinely omnipresent. If you are not running Vektor yet, the sync tool will still save you a meaningful amount of configuration overhead every time you add or update an MCP server.

And when you are ready to give your agents memory that persists across sessions, editors, and restarts, Vektor is one install away.

npm install -g @vektormemory/mcp-sync
npm install -g vektor-slipstream
GitHub: github.com/Vektor-Memory/Mcp-Sync

npm: @vektormemory/mcp-sync

Vektor Memory: vektormemory.com

Mcp Server
Ai Agentic Workflow
Claude Code
Open Source