Как создать MCP сервер на Python: код и проверка

Создать MCP-сервер можно на Python: описать одну безопасную функцию как инструмент, запустить её через официальный SDK, вызвать в Inspector и затем подключить к своему клиенту. Ниже минимальный локальный пример без внешнего API и без ключей. Вам понадобятся Python, менеджер пакетов, Node.js с командой npx по инструкции SDK и возможность запускать команды на компьютере. MCP-сервер предоставляет инструмент приложению с ИИ, но сам не является моделью. Руководство официального Python SDK.

Что именно вы создадите

В примере сервер принимает два целых числа и возвращает сумму. Такой инструмент позволяет проверить соединение и схему аргументов без доступа к личным данным. В документации SDK объяснено различие: tool вызывается по решению модели, resource отдаёт данные приложению, prompt представляет шаблон сообщения для пользователя. Если нужны только основы протокола, сначала прочитайте объяснение устройства MCP-сервера.

Практическое правило выбора: начинайте с локального режима stdio, когда клиент и сервер работают на одном компьютере. Сетевой HTTP нужен, если к серверу должны подключаться разные процессы по сети; тогда до публикации придётся продумать доступ и защиту. Официальный SDK описывает варианты подключения. Здесь HTTP не открываем.

Как подготовить проект

Используйте отдельную папку и виртуальное окружение проекта, чтобы не менять пакеты других приложений. Официальная инструкция по установке SDK указывает Python 3.10 или новее и пакет mcp[cli]. Если на вашем компьютере установлен uv, выполните команды ниже. Вариант с pip install "mcp[cli]" также есть в документации, но для повторяемого проекта лучше зафиксировать зависимости.

mkdir my-mcp-server
cd my-mcp-server
uv init
uv add "mcp[cli]"

Проверьте, что команды завершились без ошибки и в папке проекта появился файл зависимостей. Если uv не установлен, сначала поставьте его по официальной инструкции вашей системы или используйте уже принятый в проекте способ установки Python-пакетов. Не копируйте в server.py ключи и пароли: для первого теста они не нужны.

По теме: ИИ-агент: память между сеансами без ошибок и утечек

Как написать минимальный сервер

Создайте файл server.py со следующим содержимым. Импорт и декоратор соответствуют актуальному примеру официального SDK. Типы аргументов задают схему инструмента, а строка описания помогает клиенту показать назначение функции.

from mcp.server import MCPServer

mcp = MCPServer("Calculator")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Сложить два целых числа."""
    return a + b

if __name__ == "__main__":
    mcp.run()

Здесь нет сетевого порта и внешней базы. Сервер ждёт вызова клиента. Не добавляйте print() при запуске в стандартный вывод: при stdio он служит каналом протокола. Документация подключения советует направлять диагностику в журнал ошибок. Дополнительные инструменты добавляйте только после того, как базовый вызов работает.

Как проверить инструмент до подключения к агенту

Запустите Inspector из папки проекта командой uv run mcp dev server.py. Официальный путь тестирования открывает интерфейс, в котором можно увидеть инструменты и вызвать каждый вручную. Найдите add, введите a = 2 и b = 3, затем убедитесь, что результат равен 5.

1. Выполните uv run mcp dev server.py и откройте адрес, который покажет команда.
2. Подключитесь к локальному серверу в Inspector и откройте список Tools.
3. Выберите add, передайте два целых числа и вызовите инструмент.
4. Сравните ответ с обычным сложением. Повторите с отрицательным числом и нулём.

Проверяемый результат: Inspector показывает инструмент add, принимает два целых числа и возвращает ожидаемую сумму. Если инструмента нет в списке, сервер ещё не готов к подключению в рабочий агент.

Это одновременно проверочный список и граничный случай: -2 + 0 должно дать -2. Передавать строку вместо числа не следует считать успешным тестом функции; такой вызов проверяет ошибку схемы. SDK объясняет, что клиент строит форму аргументов по аннотациям типов.

По теме: Атаки на ИИ-агентов: как проверить и закрыть опасные действия

Как подключить сервер к клиенту

После ручной проверки зарегистрируйте локальную команду запуска в приложении, где будете использовать инструмент. Нужен абсолютный путь к server.py; относительный путь часто ведёт к ошибке, потому что клиент запускает сервер из своего рабочего каталога. Официальный пример подключения показывает команды и конфигурации для разных клиентов. После изменения настроек перезапустите приложение и проверьте, что инструмент появился.

Не смешивайте создание собственного сервера с подключением готового. Если ваша цель лишь добавить существующий MCP-инструмент в Codex, используйте инструкцию по подключению MCP к Codex. Для собственного инструмента сначала добейтесь работы в Inspector, затем переходите к настройке клиента.

Безопасность и типовые ошибки

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

• Inspector не видит сервер: сначала проверьте ошибку запуска server.py и установленный пакет.
• Клиент не находит файл: укажите абсолютный путь и перезапустите клиент.
• Соединение обрывается: уберите вывод отладочного текста в stdout, проверьте сообщения в stderr.
• Инструмент отвечает неверно: вызовите его с заведомо известными входными данными и проверьте код функции отдельно.

Если публикация сервера требует сетевого доступа, не переносите локальный пример на открытый адрес без отдельной схемы авторизации. Локальный stdio подходит для обучения и личного прототипа; общий сервер требует дополнительных решений по доступам и эксплуатации.

Частые вопросы

Нужно ли знать протокол JSON-RPC вручную?

Для первого сервера нет. SDK берёт обмен сообщениями на себя; вы пишете функции и описываете их типы. Это видно в официальном примере.

Почему сервер ничего не печатает при запуске?

В режиме stdio он ждёт сообщения клиента. Отсутствие обычного приветствия допустимо; немедленное завершение или ошибка запуска требуют диагностики.

Можно ли сразу дать инструменту доступ к базе данных?

Технически можно, но сначала задайте только чтение, ограничьте область данных и продумайте подтверждение действий. Для первого опыта сложение безопаснее и легче проверить.

Что выбрать, Python или TypeScript?

Выберите язык, который уже используется в проекте. Пример здесь использует официальный Python SDK; официальный TypeScript SDK предлагает иной путь с тем же принципом инструментов.