MCP Integration

AgentSync can automatically generate and synchronize MCP (Model Context Protocol) configuration files for multiple agents. This allows you to define your MCP servers once and use them everywhere.

Configuration

Add the [mcp] section to your agentsync.toml:

[mcp]
enabled = true

# Strategy for existing files: "merge" (default) or "overwrite"

merge_strategy = "merge"

Merge Strategy

• merge (Default): AgentSync will read the existing agent-specific config file, add the servers defined in your TOML, and preserve existing servers that are not in the TOML. If a conflict occurs (same server name), the TOML configuration wins.
• overwrite: AgentSync will completely replace the agent-specific config file with the servers defined in your TOML.

Reverting MCP Configurations

agentsync revert uses the apply-time snapshot to restore the MCP config file, rather than trying to identify managed servers by name or value. When apply writes an MCP config, AgentSync records the complete original file content and the state it wrote. The snapshot covers the whole file, including top-level settings and plugin-generated MCP output.

Restore is conditional:

• If the file still matches the state recorded by apply, revert restores the original content exactly.
• If the file did not exist before apply, revert removes the generated regular file only if it still matches the recorded state.
• If the file changed after apply, became a symlink, fails journal validation, or the selected agents omit an owner of a shared MCP destination, revert preserves the file and journal and reports a skip or error. It does not merge later edits into the snapshot.
• If an intentional edit blocks a later apply, back up the file and use agentsync apply --rebase-mcp-journal to explicitly continue. The apply uses the configured merge strategy and refreshes the journal hashes while retaining the original pre-first-apply snapshot and owners. A later revert still restores that original snapshot and can discard edits made since the first apply; inspect the MCP config after rebasing.

For a skipped restore, safely save or resolve any later edits and retry revert with every recorded owner selected. Copilot and VS Code share .vscode/mcp.json, so that file is restored only when every owner recorded for it is included. Restore uses the recorded agent IDs even if an agent or [mcp] is now disabled; --agents and default_agents still control which owners are selected.

If there is no journal from an earlier AgentSync version, revert cannot reconstruct the pre-apply file. It leaves the MCP config as-is and warns when relevant; it does not delete servers based on their names or values. Reverting plugin-generated MCP output uses the same snapshot and does not resolve, materialize, or run plugins.

This snapshot mechanism applies uniformly to all 10 MCP formats, including Claude Desktop (global config), Gemini CLI, OpenCode, and Z-Code, whose files carry extra top-level settings alongside the server list. Those settings are preserved by the byte-exact restore, so no format-specific removal logic is needed.

Journal location and privacy

The journal is stored at AGENTSYNC_DATA_DIR/agentsync/mcp-ownership/<sha256-canonical-project-root>/ownership.json when AGENTSYNC_DATA_DIR is set; otherwise it uses dirs::data_local_dir()/agentsync/mcp-ownership/<sha256-canonical-project-root>/ownership.json. A project rooted exactly at the user’s home directory may use the OS default local data directory beneath that root. An explicit AGENTSYNC_DATA_DIR must still resolve outside the project root, even for a home-directory project. The platform data directory is:

If $HOME is itself a Git repository (for example, a dotfiles repository), the default journal directory is inside that repository root. The journal files are permission-restricted, but Git permissions do not prevent the same user from staging them; ensure .local/share/agentsync is ignored or do not stage its files.

• Linux: $XDG_DATA_HOME when set, otherwise $HOME/.local/share.
• macOS: $HOME/Library/Application Support.
• Windows: %LOCALAPPDATA% (LocalAppData).

The snapshot may contain credentials or tokens from the original MCP config. AgentSync never logs the content. On Unix, state directories use mode 0700 and files use mode 0600. On Windows, AgentSync applies and verifies a protected DACL granting full control only to the current process-token user.

Journal records have no expiry or automatic cleanup. A record remains until its MCP config is successfully restored. agentsync clean does not remove the journal. After successful restore, the record is removed, but the empty ownership.lock file remains. --keep-backups applies only to .bak symlink backups; it does not retain an MCP journal after successful restore. --dry-run does not create or change MCP files or journal state. Symlinked MCP config files are refused rather than followed or replaced.

Claude Desktop’s MCP config is global, while its journal record belongs to the project that ran apply. AgentSync apply and revert operations targeting the same MCP path are serialized by a shared per-path lock when the projects use the same default data directory or the same absolute AGENTSYNC_DATA_DIR. Relative overrides are rejected because they can resolve differently from different project working directories. If projects sharing a global MCP path use different override directories, their locks are separate; configure the same absolute override for all of them. A change detected before the final publish or restore check is preserved, and revert retains its journal record. This lock coordinates AgentSync processes only: an external editor that writes during the final compare-and-publish (or compare-and-remove) window is not coordinated and can still race with the operation.

• Claude Code — .mcp.json (agent id: claude) — JSON; Standard format
• Claude Desktop — Global OS-dependent config (agent id: claude-desktop) — JSON; Global; disabled by default
• GitHub Copilot — .vscode/mcp.json (agent id: copilot) — JSON; Shared with VS Code
• OpenAI Codex CLI — .codex/config.toml (agent id: codex) — TOML; Maps headers to http_headers
• Gemini CLI — .gemini/settings.json (agent id: gemini) — JSON; Adds trust: true
• VS Code — .vscode/mcp.json (agent id: vscode) — JSON; Shared with GitHub Copilot
• Cursor — .cursor/mcp.json (agent id: cursor) — JSON; Standard format
• OpenCode — opencode.json (agent id: opencode) — JSON; Standard format
• Z-Code — .zcode/config.json (agent id: zcode) — JSON; Uses the mcp.servers object and preserves other Z-Code settings
• MiniMax Code — .mcp.json (agent id: minimax) — JSON; Project-level standard format

Defining Servers

Define your servers under [mcp_servers.<name>]:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
env = { "DEBUG" = "true" }

Server Fields

• command: The executable to run (for stdio transport).
• args: List of arguments for the command.
• env: (Optional) Key-value pairs for environment variables.
• url: (Optional) The URL for the MCP server (for HTTP/SSE transport).
• headers: (Optional) Key-value pairs for HTTP headers.
• type: (Optional) The transport type (e.g., stdio, http, sse).
• disabled: (Optional) Set to true to temporarily disable a server without removing it.

Global Agents

Some agents store their MCP configuration in a global (user-level) location rather than in the project directory. AgentSync calls these global agents.

Currently supported global agents:

Agent	Config Location
Claude Desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Global agents are disabled by default because they write outside your project directory. To enable:

[agents.claude-desktop]
enabled = true
description = "Claude Desktop"

No symlink targets are needed for global agents. They only participate in MCP server syncing. When agentsync apply runs, the MCP servers defined in your [mcp_servers] config are merged into the global config file, preserving any existing non-MCP settings (keyboard shortcuts, theme, etc.).

How it works

The Model Context Protocol (MCP) allows you to define backend servers for AI assistants in one place and sync those configurations automatically across all supported agents. This reduces duplication and mistake-prone manual steps.

Which Agents Get MCP Configs?

Important: MCP configuration files are only generated for agents that are:

1. Explicitly configured in your agentsync.toml ([agents.<name>] section exists)
2. Enabled (enabled = true)
3. Included in the current run (matches --agents filter or default_agents)

Agents not defined in your config will not receive MCP configuration files, even if they are supported.

# Example: Only claude, copilot, and gemini will get MCP configs
[agents.claude]
enabled = true

[agents.copilot]
enabled = true

# Cursor is NOT configured, so it won't get an MCP config
# Even though AgentSync supports cursor, no .cursor/mcp.json will be created

Setup instructions

1. Add the [mcp] block to your .agents/agentsync.toml and set enabled = true. Optionally set merge_strategy = "merge" | "overwrite".
2. Under [mcp_servers], define one block per MCP backend server (see example below).
3. Run agentsync apply. AgentSync will:
   • Gather all servers defined in mcp_servers.
   • For each configured and enabled agent, generate the MCP config file.
   • Perform the chosen merge (default) or overwrite strategy for existing config files.
   • Write new configuration files in the correct location.
   • Ensure parent directories exist before writing.

Best Practice: Use the merge strategy for the least surprise—existing server entries not present in your TOML will be preserved.