Настройка MCP-сервера: конфиги, переменные, отладка

Большая часть проблем с MCP - это не протокол, а конфигурация. Разберём её устройство и порядок отладки.

Структура конфига

Конфигурация - это описание серверов: имя, способ запуска и окружение. Минимально нужны две вещи.

Имя сервера. Произвольное, но оно попадает в имена инструментов, которые видит агент. Короткое и осмысленное лучше длинного: два сервера с похожими именами - готовая путаница при выборе инструмента.

Способ запуска. Для локального сервера - команда и её аргументы. Для удалённого - адрес. Здесь же указывается окружение процесса.

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

Практическая деталь, которая экономит часы: сломанный JSON часто не вызывает ошибки. Клиент читает файл, не может его разобрать и работает так, будто серверов нет вовсе. Если после правки ничего не изменилось, проверьте синтаксис в первую очередь.

Переменные окружения и секреты

Правило одно: токены живут в окружении, конфиг на них ссылается.

Почему это важнее, чем кажется:

• Проектный конфиг лежит в репозитории. Токен в нём уедет всем, кто клонирует проект.
• Удалить файл потом недостаточно: токен останется в истории git. Его придётся отзывать.
• Один и тот же конфиг у разных разработчиков должен работать с разными доступами.

Что стоит помнить про окружение сервера: это не ваша оболочка. Клиент запускает процесс сам, и переменные, экспортированные в терминале, серверу не видны. Их нужно задать там, где клиент их подхватит, - обычно прямо в записи о сервере.

Ещё одна частая ловушка: пустая переменная неотличима от отсутствующей. Сервер стартует, не может авторизоваться и отдаёт пустой список инструментов. Со стороны это выглядит как «подключился, но не работает».

Логи

Три места, где искать.

Лог клиента. Видно, запустился ли процесс и с какой ошибкой он завершился. Первое место при проблеме «сервера нет в списке».

Вывод сервера в stderr. Стандартный вывод занят протоколом, поэтому всё диагностическое идёт в stderr. Если вы пишете свой сервер, любой print в stdout ломает обмен - это самая частая ошибка новичков.

Файловый лог сервера. Самый полезный вариант для своего сервера: видно, какой инструмент вызвали, с какими аргументами и что вернулось. Без этого разбор «агент сделал не то» невозможен.

Хорошая привычка: логировать аргументы вызова. Половина проблем оказывается не в сервере, а в том, что агент передал не то, что вы ожидали, - и причина в описании инструмента.

Типовые ошибки

Симптом	Причина
Сервера нет в списке	Не перезапустили клиента, или сломан JSON
Сервер помечен упавшим	Команда не найдена; нужен полный путь
Сервер живой, инструментов нет	Провал авторизации: проверьте переменные
Инструменты есть, агент их не берёт	Расплывчатые описания
Работает у вас, не работает у коллеги	Конфиг пользовательский, а не проектный
Всё работает, но медленно	Сервер ходит во внешнюю систему на каждый вызов
Агент выбирает не тот инструмент	Два сервера с похожими именами инструментов

Отдельно про последнее: конфликт имён решается отключением лишнего сервера, а не уточнением промпта. Если два сервера дают похожие инструменты, агент будет ошибаться независимо от формулировок.

Порядок отладки

1. Запустите команду сервера руками в терминале.
2. Проверьте синтаксис конфига.
3. Перезапустите клиента.
4. Посмотрите статус сервера в списке.
5. Спросите у агента список инструментов.
6. Сделайте один безопасный вызов.

Каждый шаг отсекает свой класс причин, и вместе они закрывают почти всё. Подробности по локальному запуску - в статье про локальный сервер. Общая картина - гид по MCP.