MCP Python в минимальном варианте означает один небольшой сервер с одним инструментом: функция принимает типизированные параметры, возвращает текст и честно сообщает об ошибках. Официальный пакет строит описание инструмента из подсказок типов и строки документации, поэтому основная работа состоит в продумывании схемы входа, прав и тестов, а код занимает считанные строки. Общий обзор серверов MCP остаётся за соседними статьями, здесь только реализация и проверка маленького инструмента.
Что в сервере
Минимальный сервер MCP на Python — это файл с экземпляром сервера, функцией-инструментом и запуском через стандартный ввод-вывод. Остальное: схема входа, ошибки, права и тест.
По руководству протокола, серверы предоставляют три вида возможностей: ресурсы с данными, инструменты, которые вызывает модель с одобрения пользователя, и шаблоны запросов. Руководство сосредоточено на инструментах, и для первого сервера этого достаточно. В актуальном руководстве требуется Python 3.10 или новее и официальный пакет mcp, который ставят командой uv add с пакетом mcp[cli], а окружение готовят менеджером пакетов uv. Сервер создаётся классом MCPServer (импорт из mcp.server), а запускается вызовом run с транспортом stdio. Имена классов и версии пакета меняются, и в старых примерах встречаются другие названия, поэтому сверяйте их с текущим руководством.
- Экземпляр класса MCPServer с именем: так клиент будет видеть сервер.
- Функция-инструмент с понятным названием и описанием в строке документации.
- Типы параметров: из них пакет строит схему входа.
- Запуск с транспортом стандартного ввода-вывода для локальной работы.
- Логирование в поток ошибок, потому что вывод на экран ломает обмен сообщениями.
Что такое инструменты сервера и как их описывать, мы разбирали в статье MCP tools: что такое инструменты сервера и как их описывать, а общий порядок построения собственного сервера описан в материале MCP server своими руками.
Схема входа
Схема входа сообщает модели, какие аргументы принимает инструмент. Руководство отмечает, что класс MCPServer использует подсказки типов и строки документации для автоматического создания описания. Значит, качество схемы определяется тем, насколько аккуратно вы описали параметры.
Подумайте о том, как модель будет читать описание. Она принимает решение по двум вещам: названию и тексту описания. Название вроде «поиск_в_справочнике_сотрудников» говорит больше, чем «поиск», а описание из одной точной фразы работает лучше длинного рассказа. Укажите, когда инструмент применять и когда он бесполезен: это снижает число ложных вызовов.
| Элемент | Как задаётся | Зачем |
|---|---|---|
| Название инструмента | Имя функции | Модель выбирает инструмент по названию и описанию |
| Описание | Первая строка документации | Объясняет, когда инструмент применять |
| Параметры | Подсказки типов в сигнатуре | Определяют схему входа и допустимые значения |
| Описание параметров | Раздел аргументов в документации | Помогает модели подставлять верные значения |
| Результат | Возвращаемое значение | Текст, который увидит модель |
Узкие типы лучше широких: перечисление допустимых значений надёжнее свободной строки, а числовой параметр с понятным смыслом надёжнее текстового. Если параметр влияет на результат опасным образом, ограничьте его в самой функции, добросовестность модели в расчёт брать нельзя.
Один инструмент
Для первого сервера выберите безобидный и проверяемый инструмент: например, поиск в небольшом справочнике или чтение статуса. Такой инструмент работает только на чтение, поэтому ошибки обходятся дёшево.
Выбирайте функцию, результат которой легко проверить глазами: справочник из нескольких записей, статус сервиса, курс из внутренней таблицы. Когда вы знаете правильный ответ заранее, тест превращается в сверку и догадки отпадают. Сложные инструменты с побочными действиями оставьте на потом, после того как вся цепочка от клиента до ответа отработана на простом.
- Подготовьте проект и окружение, установите официальный пакет для Python.
- Создайте файл сервера и экземпляр сервера с именем.
- Напишите функцию-инструмент с типами параметров и подробной строкой документации.
- Внутри функции проверьте входные данные до использования и верните понятный текст.
- Добавьте запуск сервера с транспортом стандартного ввода-вывода.
- Замените вывод на экран логированием в поток ошибок: для такого транспорта любой лишний вывод портит обмен.
- Запустите сервер командой менеджера окружения и убедитесь, что он ждёт сообщений.
После этого сервер готов к подключению клиентом. Отдельная осторожность нужна с выводом: руководство прямо предупреждает, что запись в стандартный вывод повреждает сообщения протокола и ломает сервер, а для серверов по сети такого ограничения нет.
Какой безобидный инструмент вашей компании подошёл бы для первого сервера?
Ошибки и права
Инструмент вызывает модель, а значит, на вход могут прийти странные значения, пустые строки и попытки выйти за допустимое. Хорошая функция ожидает это заранее.
Ошибки полезно делить на два вида. Ошибки пользователя и модели, например неверное значение, возвращаются коротким понятным текстом, чтобы модель могла исправиться. Внутренние сбои, например недоступный источник данных, логируются подробно, а наружу уходит краткое сообщение без деталей реализации. Так модель продолжает работать, а вы получаете материал для расследования.
- Проверка ввода: пустые значения, слишком длинные строки, недопустимые символы, значения вне перечисления.
- Понятная ошибка: короткое сообщение, из которого модель поймёт, что исправить, без технических подробностей и секретов.
- Таймауты: внешние вызовы ограничены по времени, иначе зависший запрос повесит инструмент.
- Изоляция: инструмент выполняет только то, ради чего создан, а лишние файлы и сетевые доступы закрыты.
- Секреты: ключи берутся из окружения и остаются вне ответов и журналов.
- Подтверждение: инструменты, которые что-то меняют, требуют согласия человека на уровне клиента.
Сервер подключается к рабочему клиенту после теста запретов: некорректный ввод отклоняется, секреты остаются вне ответов, лишние действия невозможны. Права сервера записаны в реестре вместе с владельцем.
Общие принципы прав и секретов описаны в статье Безопасность ИИ-агентов: права, секреты и проверка, а для серверов, которые работают с контейнерами, смотрите материал Docker MCP: контейнеры, допуск и безопасный тест.
Тест клиентом
Сервер проверяется клиентом, потому что именно клиент показывает, как модель видит ваш инструмент. В руководстве для проверки используется настольное приложение, но подойдёт любой клиент MCP; о выборе читайте в статье MCP клиент: что это и как выбрать.
- Подключите сервер через настройки клиента: укажите команду запуска и путь к проекту.
- Убедитесь, что инструмент виден в списке и его описание читается понятно.
- Задайте типовой вопрос и проверьте, что модель вызывает инструмент и верно использует результат.
- Задайте вопрос на границе: пустой ввод, лишние параметры, просьба сделать запрещённое.
- Проверьте журналы сервера: видны ли вызовы, нет ли в них секретов.
- Повторите тест после изменения кода и после обновления пакета.
Тесты удобно сохранять в файле проекта как набор вопросов с ожидаемым поведением: вопрос, какой инструмент должен вызваться, какой результат ожидается. Набор прогоняется после любого изменения сервера, и вы сразу видите поломку. Для сервера, которым пользуются коллеги, такой набор превращается в страховку от случайных правок.
Запишите результаты в короткий протокол: что проверено, что сработало, что исправлено, кто и когда проверял. Подробнее о подключении серверов к клиентам читайте в материале MCP-подключения: как настроить. Если нужно построить набор рабочих инструментов MCP под ваши процессы с правами и тестами, мы делаем это в рамках консалтинга по внедрению ИИ.