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.

• 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

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.