Skip to content

MCP-серверы ​

MCP-серверы ~/.agents описываются один раз в ~/.agents/mcp.json в общем формате MCP: объект mcpServers. on переводит их в формат каждого ИИ-агента.

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "docs": {
      "type": "http",
      "url": "https://docs.example/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

Поля сервера: command, args, env, url, headers, type, disabled.

Куда вписываются серверы ​

ИИ-агентФайлФормат
Claude Code~/.claude.json ($CLAUDE_CONFIG_DIR/.claude.json)JSON, ключ mcpServers, без изменений
Codex~/.codex/config.toml ($CODEX_HOME/config.toml)TOML, таблицы [mcp_servers.<имя>]
Gemini CLI~/.gemini/settings.jsonJSON, ключ mcpServers; HTTP-сервер получает httpUrl
Grok Build~/.grok/config.toml ($GROK_HOME/config.toml)TOML, таблицы [mcp_servers.<имя>]
Остальные—вид «MCP-серверы» пропускается

Для Codex поля переводятся так: headers → http_headers, disabled: true → enabled = false. Grok получает headers как есть. Остальной текст config.toml, в том числе комментарии и другие таблицы, не меняется.

Свои и чужие записи ​

Машина помнит, какие записи вписал on. Учёт лежит в каталоге состояния (~/.agentsync/mcp/, или AGENTSYNC_STATE) и в снимок не входит.

  • Чужие записи с другими именами и остальные ключи файла on не меняет.
  • Одноимённую чужую запись on заменяет и запоминает. off её возвращает.
  • Повторный on убирает свою запись, которой в ~/.agents больше нет.
  • off удаляет только свои записи.

Если файл настроек — ссылка (например, из dotfiles), запись идёт в файл, на который она указывает; ссылка остаётся ссылкой.

Переменные секрета ​

Значение секрета в mcp.json не пишут. Вместо него пишут переменную ${NAME}, а значение кладут на машину:

  • в окружение: export GITHUB_TOKEN=…;
  • или в ~/.agents/.env:
sh
# ~/.agents/.env
GITHUB_TOKEN=ghp_…
DOCS_TOKEN=…

~/.agents/.env в снимок и публикацию не входит. Переменная ${NAME} секретом не считается: с ней снимок создаётся, и сервер публикуется. Получатель публикации кладёт своё значение у себя.

ИИ-агентКак вписывается переменная
Claude Code, Gemini CLI, Grok Build${NAME} как есть: ИИ-агент раскрывает её сам
Codexзначение из окружения или ~/.agents/.env

Если у Codex значения нет ни в окружении, ни в .env, переменная вписывается как есть, и вывод on называет её. Положите значение и повторите on.

Значение секрета в файле

Если в mcp.json лежит само значение ("GITHUB_TOKEN": "ghp_…" или "Authorization": "Bearer abc…"), снимок не создаётся, а подключение отказывает. Пояснение называет файл, но не значение.

MCP-серверы Claude Code в публикации ​

Claude Code хранит пользовательские MCP-серверы в ~/.claude.json, вне своей домашней папки и рядом с состоянием входа. Сам этот файл не публикуется. agentsync push claude кладёт в публикацию файл user.mcp.json: только раздел mcpServers, без машинных серверов.

При применении публикации Claude Code:

  • серверы, которые на машине автора вписал on, уходят в ~/.agents/mcp.json;
  • собственные серверы автора вписываются в ~/.claude.json применяющего. Остальные ключи этого файла не меняются.

Машинный MCP ​

MCP-сервер с абсолютным путём в command, args или env (например, /Users/me/tools/run.sh или C:\tools\server.exe) привязан к машине. Это решается по серверу, а не по файлу:

  • машинный сервер в публикацию не входит;
  • соседние серверы того же файла публикуются;
  • при применении и откате машинный сервер на машине остаётся.