MCP-серверы
MCP-серверы ~/.agents описываются один раз в ~/.agents/mcp.json в общем формате MCP: объект mcpServers. on переводит их в формат каждого ИИ-агента.
{
"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.json | JSON, ключ 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:
# ~/.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) привязан к машине. Это решается по серверу, а не по файлу:
- машинный сервер в публикацию не входит;
- соседние серверы того же файла публикуются;
- при применении и откате машинный сервер на машине остаётся.