Свой MCP-сервер на Python: минимальный инструмент для чтения

Чтобы создать MCP-сервер на Python, опишите узкую функцию через официальный SDK, запустите её по stdio и проверьте в MCP Inspector перед подключением редактора. Для начала подойдёт справочник с вымышленными данными только для чтения: так можно разобраться с обнаружением инструментов, аргументами и ответами без ключей доступа к рабочим системам. Ниже используется официальный Python SDK.

Что он умеет

Пример отвечает на простой вопрос службы поддержки: какую инструкцию показать по доставке или возврату? Все данные учебные. Вызывающая сторона выбирает тему и получает соответствующий текст; в функции нет операций изменения заказов, чтения файлов или обращения к сайтам.

Имя lookup_policy мы задаём сами в этом примере. Это не название инструмента готовой интеграции. У него понятный договор: разрешённая тема возвращает заранее известный ответ, неизвестная не проходит проверку. Такой первый проект легче проверить, чем помощника с неограниченным доступом к файлам.

У MCP-инструментов есть имена и схемы входных данных. Клиент получает список через tools/list, а вызывает инструмент через tools/call; обмен обслуживает SDK. В разделе спецификации об инструментах, актуальном на 30 октября 2026 года, также рекомендуется сохранять возможность запретить вызов пользователю. Основы объясняют страницы что такое MCP и чем MCP отличается от API.

Как подключить безопасно

1. Подготовьте отдельный проект. Откройте пустую папку в VS Code или привычном редакторе. По состоянию на 30 октября 2026 года документация по установке SDK описывает стабильную ветку v2 и требует Python 3.11 или новее. Код ниже рассчитан на этот API. Прежде чем соединять его с примерами из старых руководств, проверьте текущую документацию. Создайте окружение:

sh python -m venv .venv

Установите зависимость для разработки через интерпретатор этого окружения. Для macOS/Linux:

sh .venv/bin/python -m pip install 'mcp[cli]'

Для Windows PowerShell:

powershell .venv\Scripts\python.exe -m pip install 'mcp[cli]'

Перед передачей проекта зафиксируйте разрешённые версии зависимостей в lock-файле. Для упражнения используйте папку без ключей и клиентских документов.

2. Создайте server.py. Сохраните полный код. Тип Literal ограничивает допустимые значения темы. Декораторы, построение схемы по аннотациям типов и используемые здесь подсказки описаны в руководстве SDK по инструментам.

```python from typing import Literal

from mcp.server import MCPServer from mcp.types import ToolAnnotations

mcp = MCPServer("Demo policy lookup")

POLICIES = { "delivery": "Demo only: ask support about delivery changes.", "returns": "Demo only: contact support before returning an item.", }

@mcp.tool( annotations=ToolAnnotations( read_only_hint=True, open_world_hint=False, ) ) def lookup_policy(topic: Literal["delivery", "returns"]) -> str: """Return fictional guidance for an allowed support topic.""" return POLICIES[topic]

if name == "main": mcp.run(transport="stdio") ```

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

3. Проверьте запуск и откройте Inspector. Запустите файл через Python созданного окружения. Сервер stdio обычно молча ждёт протокольный ввод; это объясняется в разделе о запуске. Остановите ручной процесс перед запуском тестового клиента.

Для проверки используйте браузерный MCP Inspector. По его документации на 30 октября 2026 года нужен Node 22.19.0 или новее. Из папки проекта в macOS/Linux выполните:

sh npx @modelcontextprotocol/inspector .venv/bin/python server.py

В Windows PowerShell:

powershell npx @modelcontextprotocol/inspector .venv\Scripts\python.exe server.py

npx может скачать пакет Inspector; ознакомьтесь с запросом перед подтверждением. Откройте выведенный локальный URL и не передавайте его токен доступа другим. Подключитесь по stdio и откройте представление Tools.

4. Проверьте границы напрямую. Найдите lookup_policy и обязательный параметр topic. Передайте {"topic":"returns"}, затем {"topic":"delivery"} и сравните результаты со строками в POLICIES. Попробуйте {"topic":"billing"} и пустой объект аргументов. Оба запроса должны отклоняться, а не порождать выдуманную инструкцию. Если форма не позволяет ввести недопустимое значение, отправьте тот же вызов через CLI Inspector. Сначала установите поведение функции, затем переходите к пересказу ответа ассистентом.

5. Зарегистрируйте команду запуска в клиенте. Для MCP-клиента VS Code создайте .vscode/mcp.json или аккуратно добавьте запись в существующий файл. Обёртка servers описана в официальном руководстве по подключению к приложениям:

json { "servers": { "demo-policy": { "type": "stdio", "command": "/absolute/path/to/project/.venv/bin/python", "args": ["/absolute/path/to/project/server.py"] } } }

Замените оба пути настоящими абсолютными путями. В Windows укажите python.exe из окружения; обратные слеши в JSON экранируйте либо используйте прямые. Изучите запрос доверия серверу и проверьте состояние командой MCP: List Servers. В редакторе также должен быть включён чат-клиент с поддержкой MCP; его текущие требования к аккаунту проверяйте отдельно. Подробнее — в руководстве по MCP в VS Code.

6. Проследите вызов из чата. Попросите клиент вызвать lookup_policy для возврата. Посмотрите реальные аргументы и результат, затем сравните ответ с учебным текстом. На время знакомства оставьте подтверждения включёнными. Сам по себе убедительный ответ в чате даёт меньше оснований для доверия, чем видимый вызов и полученные данные.

Когда это не работает

Ошибка импорта часто означает, что команда использует другое окружение Python либо установленный SDK не соответствует примеру. Выполните в терминале ровно ту команду, которая записана в настройках, и сверяйтесь с текущей документацией SDK. Сервер также может не появиться из-за старой конфигурации клиента или относительного пути, разрешившегося в другой папке; эти случаи разобраны в руководстве по подключению.

Пишите диагностические сообщения в stderr через Python logging. Официальное руководство по созданию сервера предупреждает: stdout служит каналом протокола stdio. Приветствие при запуске или вывод скрипта-обёртки могут нарушить обмен.

Режим чтения не обеспечивает конфиденциальность. Для упражнения берите только разрешённые учебные тексты: клиент может включить результат в разговор. Подключение файлов, базы или удалённого API требует пересмотра проекта. Сначала определите права доступа, фильтрацию ответа и эксплуатационные ограничения с помощью списка проверок безопасности. Для командного сервиса нужен отдельный план развёртывания и контроля доступа; смена транспорта на HTTP этих решений не заменяет.

Где здесь Tvijo

По состоянию на 30 октября 2026 года расширение DSHREM для VS Code позволяет задавать вопросы о выделенном коде прямо в редакторе. Откройте его рядом с server.py, чтобы обсудить функцию или ошибку проверки, а Inspector запускайте самостоятельно в терминале. TvijoCode включает расширение в тестовую сборку редактора; опубликованное описание указывает на неподписанные Windows-сборки без автоматического обновления. Выбирайте редактор с учётом правил установки в вашей организации.

Статус выпуска Tvijo MCP показывает отдельную роль сервера на реальном примере. По состоянию на 30 октября 2026 года отчёт о выпуске от 28 октября описывает опубликованную консультацию в пакете 0.1.1; код версии 0.2.0 с разбором diff объединён и отмечен тегом, но публикация в npm ещё ожидается. Интеграция MCP-провайдера в редактор и безопасное делегирование остаются запланированными этапами. Установка расширения сама по себе не подключает учебный сервер и не делает Tvijo универсальным клиентом для MCP-серверов.

По состоянию на 30 октября 2026 года в предложениях Tvijo Try указан за $0. Он даёт до 5 задач, 50 000 токенов или $0.05 спонсируемого использования — до первого достигнутого ограничения — из общего ежедневного пула $1, который финансирует TVIJO. Service credit показан за $10 как запрос предоплаченного кредита: использование оплачивается по фактическому объёму с сервисной наценкой 8%. Приём платежей не активирован; создание заказа не означает списания.

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

Нужен ли API-ключ для этого примера?

Серверу и прямым вызовам через Inspector не нужны ключи рабочих сервисов. У приложения с ассистентом могут быть собственные требования к аккаунту и оплате использования; проверяйте их отдельно.

Может ли этот сервер читать файлы проекта?

Данная реализация только извлекает строки из встроенного словаря. Аннотации MCP не изолируют процесс: перед запуском изменённого кода изучите его операции и права в операционной системе.

Как превратить пример в полезный рабочий инструмент?

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