Локальный MCP-сервер: запуск у себя

Локальный сервер - самый частый вариант на практике. Он проще удалённого и не требует ничего разворачивать, но у него свои особенности при запуске и отладке.

Зачем локально

Доступ к тому, что есть только у вас. Файлы на диске, локальная база, запущенный на машине сервис. Удалённый сервер до них не дотянется.

Нет сетевой поверхности. Нечего аутентифицировать и нечего выставлять наружу. Для инструментов с доступом к файлам это принципиально.

Проще запуск. Не нужно поднимать сервис, следить за его доступностью и обновлять отдельно.

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

Как он запускается

Клиент запускает сервер как дочерний процесс и общается с ним через стандартные потоки. Отсюда три следствия, которые объясняют большинство проблем:

Окружение процесса - не ваша оболочка. Переменные, которые вы задали в терминале, серверу не видны; PATH может отличаться. Поэтому в конфиге часто нужен полный путь к исполняемому файлу.

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

Жизненный цикл привязан к клиенту. Сервер стартует вместе с ним и умирает вместе с ним. Состояние между сессиями не сохраняется, если вы не сохраняете его сами.

Права доступа к файлам

Сервер работает с вашими правами. Это означает, что сервер файловых операций может дотянуться до всего, до чего дотягиваетесь вы, включая ключи в домашнем каталоге.

Что стоит сделать:

• Ограничить корневой каталог. Большинство файловых серверов принимают список разрешённых путей. Указывайте рабочий проект, а не домашний каталог.
• Разделить чтение и запись. Если задача - анализ, права на запись не нужны вовсе.
• Держать секреты вне рабочего каталога. Файл с ключами в корне проекта агент прочитает при первом же поиске по файлам, и содержимое уйдёт в контекст.
• Не запускать от администратора. Никакой пользы, а последствия ошибки шире.

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

Отладка

Порядок, который закрывает почти все случаи:

1. Запустите сервер руками в терминале. Он должен стартовать и ждать ввода, а не падать. Ошибки инициализации видны сразу, тогда как клиент их часто прячет.
2. Проверьте, что нет мусора в stdout. Приветственные сообщения и отладочные print ломают протокол.
3. Проверьте переменные окружения. Пустая переменная выглядит как отсутствующая.
4. Посмотрите логи клиента. Там обычно есть причина, по которой процесс не поднялся.
5. Проверьте зависимости. Сервер, запускаемый через менеджер пакетов, при первом старте что-то скачивает; без сети это выглядит как «просто не работает».
6. Спросите у агента список инструментов. Живой сервер с пустым списком - это провал авторизации, а не запуска.

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

Как написать свой сервер - MCP-сервер на Python. Конфигурация и переменные - настройка сервера. Общая картина - гид по MCP.