# AgentSync: синхронизация MCP-конфигов между AI-агентами одной командой

> Синхронизация MCP-серверов между Claude Code, Cursor, Codex и Gemini одной командой. AgentSync CLI: единый source of truth, конвертация JSON/TOML/MDC, дедупликация, бэкапы.
> Author: Roman Belov · Published: 2026-02-20 · Source: https://futurecraft.pro/ru/blog/agentsync-mcp-config-sync/

Работаете с несколькими AI coding agents — Claude Code, Cursor, Codex, Gemini? Значит, знаете боль ручного копирования MCP-конфигов между ними. Каждый агент хранит конфигурацию в своем формате, в своем месте, со своими особенностями. agentsync убирает эту рутину: один source of truth, одна команда — все агенты синхронизированы.

## Проблема: конфиг-дрифт при работе с несколькими агентами

MCP (Model Context Protocol) — де-факто стандарт для подключения инструментов к AI-агентам. Типичный рабочий проект сегодня использует 10-30 MCP-серверов: Supabase, GitHub, Linear, Sentry, Notion, Langfuse, Cloudflare и десятки других. Каждый сервер — это блок конфигурации с command, args, env-переменными.

Всё ломается, когда агентов больше одного. А большинство разработчиков в 2026 году используют минимум два:

- **Claude Code** хранит серверы в `~/.claude.json` (глобально) и `.mcp.json` (на уровне проекта), формат — JSON.
- **Cursor** хранит серверы в `~/.cursor/mcp.json`, формат — JSON, но с другой структурой. Правила проекта — в MDC-файлах с YAML frontmatter.
- **Codex** (OpenAI) хранит серверы в `~/.codex/config.toml`, формат — TOML. Правила — в `AGENTS.md`.
- **Antigravity/Gemini** хранит серверы в `~/.gemini/antigravity/mcp_config.json`, формат — JSON, но поддерживает только stdio-протокол.

Добавили новый MCP-сервер? Нужно отредактировать 3-4 файла вручную. Забыли один — агент молча не видит сервер. Опечатка в env-переменной — молчаливый сбой. Переименовали сервер в одном месте, но не в другом — дрифт конфигов, который вы обнаружите только когда что-то сломается.

По сути, это та же проблема configuration management, но в контексте AI-инструментов.

## Решение: agentsync

**agentsync** — CLI-утилита. Берёт конфигурацию одного агента как source of truth, генерирует конфигурации для всех остальных. Конвертация форматов, дедупликация, фильтрация, бэкапы — из коробки.

Архитектура:

```
+--------------+
|  Claude Code |  Source of Truth
|  .claude.json|  --- MCP Servers
|  .mcp.json   |  --- Rules (CLAUDE.md)
|  CLAUDE.md   |
+------+-------+
       |  agentsync sync
       +------------------+-----------------+
       v                  v                 v
+--------------+  +--------------+  +--------------+
|    Cursor    |  |    Codex     |  |  Antigravity |
|  mcp.json    |  | config.toml  |  |mcp_config.json|
| project.mdc  |  |  AGENTS.md   |  |              |
+--------------+  +--------------+  +--------------+
```

Почему Claude Code как source of truth? Самая гибкая конфигурация (3 уровня мержа: глобальный, проектный, локальный), поддержка и stdio, и HTTP-протоколов, плюс развитая система правил (CLAUDE.md).

## Быстрый старт

Установка:

```bash
pip install agentsync-cli     # pip
pipx install agentsync-cli    # pipx (рекомендуется для CLI-утилит)
uvx agentsync-cli             # uv (запуск без установки)
```

Инициализация и первая синхронизация:

```bash
agentsync init       # Создает agentsync.yaml с дефолтными настройками
agentsync sync       # Синхронизирует на все агенты
agentsync validate   # Проверяет консистентность
```

Для безопасного первого запуска — dry-run:

```bash
agentsync sync --dry-run   # Показывает что изменится, ничего не записывает
```

## Конфигурация

Вся настройка живет в одном файле `agentsync.yaml` в корне проекта:

```yaml
version: 1

source:
  type: claude
  global_config: ~/.claude.json   # Глобальный конфиг Claude Code
  project_mcp: .mcp.json         # Проектные MCP-серверы
  rules_file: CLAUDE.md           # Правила проекта

targets:
  cursor:
    type: cursor
    mcp_path: ~/.cursor/mcp.json
    rules_path: .cursor/rules/project.mdc
    rules_format: mdc              # MDC = Markdown + YAML frontmatter
    exclude_servers: []

  codex:
    type: codex
    config_path: ~/.codex/config.toml
    rules_path: AGENTS.md
    rules_format: md
    exclude_servers:
      - codex                      # Codex не может вызывать сам себя

  antigravity:
    type: antigravity
    mcp_path: ~/.gemini/antigravity/mcp_config.json
    protocols:
      - stdio                      # Только stdio-серверы (без HTTP)

rules:
  exclude_sections:
    - "MCP Servers"                # Секции, специфичные для Claude Code
    - "Context Management & Agents"

sync:
  backup: true
  backup_dir: .agentsync/backups
```

Несколько деталей:

- **exclude_servers** — исключает конкретные серверы для конкретных агентов. Типичный пример: Codex не может вызывать свой собственный MCP-сервер.
- **protocols** — фильтрация по типу протокола. Antigravity/Gemini поддерживает только stdio, поэтому HTTP-серверы автоматически отсеиваются.
- **exclude_sections** — секции из CLAUDE.md, которые не должны попадать в правила других агентов. Например, инструкции по работе с MCP-серверами или управлению контекстом специфичны для Claude Code.

## Как работает пайплайн синхронизации

Что делает `agentsync sync`:

```
agentsync sync
  |
  +- Load config (agentsync.yaml)
  +- Read source (Claude Code)
  |   +- ~/.claude.json         -> global MCP servers
  |   +- .mcp.json              -> project MCP servers
  |   +- CLAUDE.md              -> rules sections
  |
  +- Deduplicate (case-insensitive)
  +- Filter (exclude_servers, exclude_sections, protocols)
  |
  +- Generate + Write per target
      +- Cursor:       mcp.json + project.mdc (MDC frontmatter)
      +- Codex:        config.toml (marker-based) + AGENTS.md
      +- Antigravity:  mcp_config.json (stdio-only)
```

### Трехуровневый мерж источника

Claude Code хранит серверы на трех уровнях, и agentsync мержит их с приоритетами (от низшего к высшему):

1. `~/.claude.json` — глобальные серверы (top-level `mcpServers`)
2. `~/.claude.json` — проектные серверы (`projects[путь].mcpServers`)
3. `.mcp.json` — локальные серверы (перезаписывают все предыдущие)

### Case-insensitive дедупликация

Разные источники конфигов иногда называют один и тот же сервер по-разному: `Notion` в глобальном конфиге и `notion` в проектном. agentsync находит такие конфликты, оставляет запись с более высоким приоритетом и пишет warning в лог.

### Конвертация форматов

Каждый адаптер пишет конфиг в нативном формате агента:

- **Cursor** — JSON с `mcpServers` объектом, правила в MDC с YAML frontmatter (`alwaysApply: true`)
- **Codex** — TOML с `[mcp_servers.name]` таблицами, вставляемый между маркерами `# === AGENTSYNC START ===` / `# === AGENTSYNC END ===` (остальной config.toml не трогается)
- **Antigravity** — JSON, только stdio-серверы

### Бэкапы и безопасность

Перед каждой записью agentsync делает бэкап в `.agentsync/backups/`. Отключить — флагом `--no-backup`. Dry-run режим (`--dry-run`) показывает все изменения без записи на диск.

## Архитектура: адаптеры

agentsync построен на паттерне адаптеров. Каждый AI-агент реализует интерфейс `TargetAdapter`:

```python
class TargetAdapter(ABC):
    @abstractmethod
    def generate_mcp(self, servers: dict[str, ServerConfig]) -> str | dict:
        """Генерация MCP-конфига в формате целевого агента."""

    @abstractmethod
    def generate_rules(self, sections: list[Section]) -> str:
        """Генерация правил в формате целевого агента."""

    @abstractmethod
    def write(self, dry_run: bool = False) -> list[WriteResult]:
        """Запись сгенерированных конфигов."""

    @abstractmethod
    def validate(self) -> list[ValidationResult]:
        """Валидация существующих конфигов."""
```

Для добавления нового агента нужно:

1. Создать `src/agentsync/adapters/youragent.py` с реализацией `TargetAdapter`
2. Зарегистрировать в `cli.py` (функция `create_targets`)
3. Добавить тип в `KNOWN_TARGET_TYPES` в `config.py`
4. Написать тесты

Структура проекта:

```
src/agentsync/
+-- adapters/           # Source и target адаптеры
|   +-- base.py         # Абстрактные базовые классы
|   +-- claude.py       # Claude Code source adapter
|   +-- cursor.py       # Cursor target adapter
|   +-- codex.py        # Codex target adapter
|   +-- antigravity.py  # Antigravity/Gemini target adapter
+-- utils/              # Утилиты
|   +-- backup.py       # Бэкапы файлов
|   +-- dedup.py        # Case-insensitive дедупликация
|   +-- diff.py         # Отображение различий серверов
|   +-- io.py           # Запись файлов с WriteResult
|   +-- logger.py       # Rich-логирование
|   +-- markdown.py     # Парсинг Markdown-секций
|   +-- output.py       # Форматирование вывода CLI
+-- cli.py              # Click CLI команды
+-- config.py           # Загрузка YAML-конфига
+-- sync.py             # Оркестратор синхронизации
+-- validate.py         # Оркестратор валидации
```

Минимум зависимостей — всего три: Click (CLI), PyYAML (конфиг), Rich (форматированный вывод). TOML генерируется вручную, без внешних зависимостей — ради совместимости с Python 3.9+.

## CLI: полный набор команд

```bash
# Синхронизация
agentsync sync                  # Полная синхронизация (MCP + rules)
agentsync sync --dry-run        # Предпросмотр без записи
agentsync sync --mcp-only       # Только MCP-конфиги
agentsync sync --rules-only     # Только правила
agentsync sync -t cursor        # Синхронизация только на конкретный агент
agentsync sync --no-backup      # Без создания бэкапов

# Валидация
agentsync validate              # Проверка консистентности
agentsync validate -v           # Подробный отчет (включая пройденные)
agentsync validate -t codex     # Валидация конкретного агента

# Инициализация
agentsync init                  # Создать agentsync.yaml
agentsync init --force          # Перезаписать существующий

# Статус
agentsync status                # Информация об источнике, состояние целей, дрифт
```

Exit codes для интеграции в CI/CD:

| Код | Значение |
|-----|----------|
| `0` | Успех |
| `1` | Runtime-ошибка (синхронизация или валидация не прошла) |
| `2` | Ошибка конфигурации (нет конфига, невалидный YAML, неизвестный адаптер) |

## Качество кода и CI/CD

Проект использует строгий CI-пайплайн на GitHub Actions:

- **Линтинг**: Ruff (check + format)
- **Типизация**: mypy со строгими настройками
- **Тестирование**: pytest на матрице Python 3.9-3.13 x Ubuntu/macOS (10 комбинаций)
- **Покрытие**: 192 теста, 97% coverage
- **Сборка**: hatchling + twine check
- **Релиз**: PyPI trusted publisher (OIDC, без токенов в секретах)
- **Dependabot**: автоматическое обновление зависимостей

Все тесты используют `tmp_path` fixtures — реальные пользовательские файлы не трогаются.

## Практический пример

Допустим, в вашем проекте используется 15 MCP-серверов: Supabase, GitHub, Linear, Sentry, Notion, Langfuse, Cloudflare, Context7, Playwright, Mapbox и другие. Основная работа — в Claude Code, Cursor для быстрых правок, Codex — для code review.

Без agentsync: добавили Grafana MCP-сервер в `.mcp.json` для Claude Code. Через два дня открываете Cursor — Grafana недоступна. Вручную копируете конфиг, адаптируете формат. Ещё через неделю нужен Codex — снова ручная конвертация JSON в TOML.

С agentsync:

```bash
# Добавили Grafana в .mcp.json (как обычно)
# Одна команда — все агенты обновлены
agentsync sync

# Вывод:
# Sync complete: 3 targets, 6 files written, 0 errors
#   cursor           v  2 files
#   codex            v  2 files
#   antigravity      v  1 file
```

Можно встроить в pre-commit hook или CI:

```bash
agentsync validate || echo "MCP configs out of sync!"
```

## Ссылки

- GitHub: [github.com/spyrae/agentsync](https://github.com/spyrae/agentsync)
- PyPI: [pypi.org/project/agentsync-cli](https://pypi.org/project/agentsync-cli/)
- Лицензия: MIT
- Python: 3.9+

---

*Нужна помощь с настройкой AI-агентов и MCP-инфраструктуры? Я помогаю стартапам внедрять AI-решения и строить продукты — [belov.works](https://belov.works).*

---

*agentsync — open-source проект от Spyrae. Баг-репорты, feature-реквесты и PR приветствуются.*

## Связанные статьи

- [MCP в продакшене: от настройки до custom-серверов](/ru/blog/mcp-production-custom-servers/) — как строить и эксплуатировать MCP-серверы, которые agentsync синхронизирует между агентами
- [Multi-Agent Architecture: когда одного AI недостаточно](/ru/blog/multi-agent-architecture/) — проектирование систем, где несколько агентов работают вместе, каждый со своими MCP-конфигами
- [Context Engineering: управление контекстным окном LLM](/ru/blog/context-engineering-guide/) — структурирование контекста для LLM, включая роль MCP-серверов в подаче контекста агентам
- [LLM Observability с Langfuse](/ru/blog/llm-observability-langfuse/) — мониторинг LLM-вызовов, которые производят агенты с MCP-подключениями