Создание самодиагностирующегося сервера MCP: три хоста, три механизма, подводные камни

Настройка MCP-сервера до сих пор часто означает ручное редактирование JSON-файла — и каждый хост использует свой файл и формат. Это трение мешает разработчикам запускать серверы, которыми они иначе пользовались бы. В этом посте разбираются три хоста, их механизмы установки и подводные камни, которые вас подстерегают.

Три хоста, три механизма

• VS Code: Есть настоящий API — registerMcpServerDefinitionProvider. Объявите провайдер в package.json и возвращайте определение сервера во время выполнения. VS Code показывает запрос на согласие. Никакого редактирования конфигурационных файлов. Самый чистый способ, но требует выпуска расширения VS Code.
• Cursor: Нет нативного API. Записывайте .cursor/mcp.json напрямую с корневым ключом mcpServers.
• Claude Code: Используйте CLI. Не пишите файл вручную. Запустите, например:
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

Шесть подводных камней, которых стоит опасаться

1. Этот JSON-файл не ваш. mcp.json в Cursor хранит и другие серверы пользователя. Прочитайте, объедините вашу запись, сохраните остальные ключи — не перезаписывайте.
2. Переживите некорректный файл. Если файл существует, но является невалидным JSON, не считайте его пустым и не перезаписывайте. Аналогично при ошибках чтения/прав доступа — выбрасывайте исключение. Отношение «не удалось прочитать» как «ничего нет» испортит конфигурации.
3. Сделайте резервную копию + атомарная запись. Скопируйте существующий файл перед его изменением, запишите во временный файл, затем переименуйте поверх целевого. Наполовину записанный mcp.json ломает редактор.
4. Повторная установка должна быть не ошибкой, а отсутствием операции. CLI Claude выдает ошибку, если запись уже существует — поэтому используйте remove, затем add. Для файловых хостов используйте ключ по имени сервера и заменяйте на месте. Повторный запуск должен сходиться, а не дублировать.
5. Область видимости меняет всё. Установка на уровне пользователя или проекта меняет расположение конфига и требования к серверу (например, явный каталог данных vs. восходящий поиск). Выбирайте осознанно.
6. Вы отвечаете за актуальность. Зарегистрированная версия расходится с той, что вы поставляете. Добавьте проверку: «соответствует ли установленная версия той, что я в комплекте?» и чистый путь переустановки. Одна кнопка показывает состояние: установить, обновить или актуально.

Главный урок: ручная настройка проваливается, потому что человек, вставляющий фрагмент, не знает абсолютного пути, правильной области видимости, переменных окружения или того, как безопасно объединить. Установочный код знает.