Первый MCP-сервер на Python за 30 строк: учим ИИ вызывать нашу функцию

MCP-сервер превращает Python-функцию в инструмент, который ИИ может обнаружить и вызвать сам. Для первого рабочего примера не нужен веб-сервер, база данных или ручная JSON-схема. Мы опишем функцию с типами, откроем её в MCP Inspector и увидим структурированный ответ.

Представьте, что вы просите ИИ оценить прогресс по курсу. Без инструмента модель рассуждает по тексту и может ошибиться в арифметике. С инструментом она передаёт два числа функции, получает точный процент и формулирует ответ. Модель выбирает момент вызова, но расчёт выполняет Python. Так MCP подключает к ассистентам файлы, API и внутренние сервисы по общему протоколу.

Что происходит между ИИ и Python-функцией

В цепочке есть три роли. Host является приложением, в котором пользователь общается с моделью. Внутри host работает MCP-клиент. Он подключается к вашему серверу, запрашивает список возможностей и передаёт вызовы. Сам сервер не разговаривает с моделью и не решает, когда нужен инструмент. Он принимает уже сформированные аргументы, запускает функцию и возвращает результат. В примере сервер называется Study Progress, а инструмент estimate_progress принимает solved и total. Такой проект легко проверить, потому что расчёт детерминированный: одинаковые числа всегда дают одинаковый процент.

MCP не делает функцию умнее и не прячет её поведение. Он описывает безопасный договор: имя, назначение, типы входных данных и формат ответа. Чем уже этот договор, тем проще тестировать сервер и понимать действия модели.

Запрос проходит четыре понятных слоя. Результат возвращается по той же цепочке

Создаём MCP-сервер и запускаем Inspector

Установите uv, создайте каталог командой uv init mcp-study, перейдите в него и добавьте SDK: uv add "mcp[cli]". Затем замените содержимое server.py кодом ниже. В актуальном Python SDK v2 сервер импортируется как MCPServer из mcp.server. Типы int и возвращаемый словарь нужны не только редактору: по ним SDK строит описание инструмента для клиента.

from mcp.server import MCPServer

mcp = MCPServer("Study Progress")


@mcp.tool()
def estimate_progress(solved: int, total: int) -> dict[str, int | str]:
    """Calculate completed practice as a percentage."""
    if total <= 0:
        raise ValueError("total must be greater than zero")
    if solved < 0 or solved > total:
        raise ValueError("solved must be between 0 and total")

    percent = round(solved / total * 100)
    if percent == 100:
        status = "готово"
    elif percent >= 70:
        status = "осталось немного"
    else:
        status = "продолжайте практику"

    return {"percent": percent, "status": status}

У каждого слоя своя работа. Инструмент не заменяет модель, а даёт ей проверяемое действие

Откуда берётся схема инструмента

Когда клиент подключается, сервер объявляет capability tools. Затем клиент запрашивает tools/list и получает имя estimate_progress, текст из docstring и JSON Schema, собранную из аннотаций типов. Если модель решает, что функция поможет ответить, host показывает или выполняет вызов по своим правилам. Запрос tools/call содержит имя и аргументы. SDK превращает значения в параметры Python, запускает функцию и упаковывает словарь в структурированный ответ. Мы не писали JSON-RPC, обработчик маршрута и схему вручную, но все эти слои остаются проверяемыми через Inspector.

Inspector запускает сервер по stdio: протокольные сообщения идут через стандартные потоки, поэтому не печатайте отладочный текст в stdout. Для логов используйте механизм SDK или stderr. Локальный stdio удобен для первого инструмента и не открывает порт наружу. Не передавайте функции больше прав, чем ей нужно. Для чтения заметок ограничьте каталог, для отправки сообщения требуйте явный текст и адресат. MCP стандартизирует соединение, но разрешения остаются вашей задачей.

Проверяем правильные и ошибочные вызовы

Откройте Inspector и сначала вызывайте функцию вручную. Так вы отделите ошибку сервера от поведения модели. Проверьте нормальный прогресс, ноль решённых задач, полное завершение и три неверных набора. Затем переименуйте solved в completed и посмотрите, как изменилась форма. После этого подключите сервер к поддерживаемому MCP-host и сформулируйте запрос без имени функции: «Я решил 7 задач из 10, сколько процентов готово?». В журнале должен появиться именно один вызов estimate_progress.

До подключения к реальному host. Сначала ручной вызов, потом решение модели

Расширяем сервер без потери контроля

Следующим шагом добавьте resource с учебным планом или второй tool для выполненной задачи. Не объединяйте чтение и запись в manage_everything. Отдельные инструменты проще описывать и тестировать. Для каждого действия определите минимальный вход, изменение после вызова и видимый результат. Для записи ограничьте тестовый каталог, для API храните ключ в переменной окружения и задайте таймаут. Так пример вырастет в сервер, которому можно доверять.

Как изучить тему в Кодике

В Кодике эту тему лучше проходить не с протокола, а снизу вверх. Сначала закрепите функции, словари, исключения и типы Python. Затем разберите, как программа получает внешние данные. Только после этого возвращайтесь к MCP и подключайте один безопасный инструмент. Такой порядок позволяет видеть в декораторах знакомый код, а не набор непонятных символов.

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

Что получится в итоге

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