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 (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.

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	.vscode/mcp.json	Shared with VS Code
OpenAI Codex CLI	.codex/config.toml	TOML format ([mcp_servers.<name>]); AgentSync maps headers to http_headers
Gemini CLI	.gemini/settings.json	Automatically adds "trust": true
VS Code	.vscode/mcp.json	For VS Code extensions
Cursor	.cursor/mcp.json	Standard format
OpenCode	opencode.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.

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.