Обзоры инструментов

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

Что такое синхронизация MCP-конфигов?

Синхронизация MCP-конфигов — это поддержание согласованности настроек серверов Model Context Protocol между несколькими AI-агентами (Claude Code, Cursor, Codex, Gemini), каждый из которых хранит конфиги в своём формате и в своём месте. Без синхронизации добавление или изменение MCP-сервера в одном агенте требует ручного дублирования изменений во всех остальных.

TL;DR

  • -agentsync использует Claude Code как единственный source of truth и синхронизирует MCP-конфиги в Cursor, Codex и Gemini одной командой
  • -Каждый агент хранит конфиги в своём формате: JSON (Claude/Cursor), TOML (Codex), MDC (Cursor rules) — agentsync конвертирует автоматически
  • -Ошибки регистра вроде 'Notion' vs 'notion' вызывают тихие баги; agentsync дедублирует при синхронизации
  • -Установка через pip/pipx/uvx; Python 3.9+, три зависимости: Click, PyYAML, Rich
  • -Три команды: agentsync init → agentsync sync → agentsync validate

Работаете с несколькими 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).

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

Установка:

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

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

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

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

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

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

Вся настройка живет в одном файле agentsync.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:

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: полный набор команд

# Синхронизация
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Успех
1Runtime-ошибка (синхронизация или валидация не прошла)
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:

# Добавили 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:

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

Ссылки

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

FAQ

Если обновить переменные окружения сервера напрямую в mcp.json Cursor, минуя Claude Code, перезапишет ли следующий agentsync sync эти изменения?

Да — sync всегда перезаписывает целевые файлы тем, что находится в источнике Claude Code. Любые правки напрямую в Cursor, Codex или Antigravity считаются временными. Правильный рабочий процесс: вносить все изменения в ~/.claude.json или .mcp.json Claude Code, затем синхронизировать. Если нужны переменные окружения, специфичные для агента, которые не должны распространяться (например, другой API endpoint в Cursor), используйте exclude_servers, чтобы исключить этот сервер из синхронизации и управлять им вручную.

Адаптер Codex использует marker-based вставку для сохранения содержимого config.toml. Что произойдёт, если кто-то случайно удалит маркеры AGENTSYNC START/END?

При следующей синхронизации agentsync не найдёт маркеры и добавит новый управляемый блок в конец файла. В результате возникнут дубликаты записей MCP-серверов — старые без маркеров и новые внутри пересозданного блока. Запустите agentsync validate -t codex для обнаружения: команда сообщит об ошибке консистентности, так как серверы из источника не соответствуют ожидаемым между маркерами. Решение: вручную удалить дублированные записи и позволить agentsync sync пересоздать маркированный блок.

Не рискует ли синхронизация правил CLAUDE.md в AGENTS.md попасть в Codex Claude-специфичными инструкциями, ломающими его поведение?

Именно для этого существует конфигурация rules.exclude_sections. Секции вроде «MCP Servers», «Context Management & Agents» и любые инструкции, специфичные для рабочих процессов Claude Code, должны быть там перечислены. Частая ошибка — забыть исключить секции, ссылающиеся на Claude-специфичные slash-команды или управление памятью: Codex получит эти инструкции и либо проигнорирует их, либо поведёт себя непредсказуемо. После первой синхронизации запустите agentsync validate -v для проверки утечек исключённых секций.