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.

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.
• args: List of arguments for the command.
• env: (Optional) Key-value pairs for environment variables.
• disabled: (Optional) Set to true to temporarily disable a server without removing it.

Supported Agents

AgentSync automatically knows where to place the MCP configuration for these assistants:

Assistant	Destination File	Notes
Claude Code	.mcp.json	Standard format
GitHub Copilot	.copilot/mcp-config.json	Copilot specific
Gemini CLI	.gemini/settings.json	Automatically adds "trust": true
VS Code	.vscode/mcp.json	For VS Code extensions
OpenCode	.opencode/mcp.json

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.

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 supported agent, check if an MCP config file should exist.
   • 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.