MCP-сервер на Python: от первого инструмента до HTTP

У первого полезного сервера должна быть простая задача: принять ID заказа и вернуть его статус. С неё и начните. Универсальный инструмент для работы с базой данных заставляет модель принимать слишком много решений и даёт ей больше доступа, чем нужно для этого сценария.

В этом руководстве мы следуем актуальному официальному примеру создания сервера. По состоянию на 7 октября 2026 года документация опирается на спецификацию MCP 2026-07-28 и официальный Python SDK — библиотеку, которая обрабатывает сообщения MCP, — с API MCPServer. В примере закреплена версия SDK 2.3.0, чтобы инструкции по импорту из старого руководства незаметно не повлияли на установленную версию.

Какие возможности открывает MCP-сервер

MCP-сервер можно представить как службу приёма запросов между ИИ-приложением и вашими системами. Приложение узнаёт, какие действия доступны, отправляет запрос и получает результат. Что именно разрешено делать, определяет ваш код.

MCP, или Model Context Protocol, задаёт общий формат такого обмена. Хост — это приложение, которым вы пользуетесь, например Claude Code или Cursor. Его клиент ведёт обмен по протоколу с вашим сервером. Это роли в системе, а не три дополнительных приложения, которые придётся установить.

Инструмент может только читать данные. Название «ресурс» не отменяет проверки доступа. Промпт задаёт инструкции, но не выдаёт права. Поддержка возможностей и способ их отображения зависят от клиента, поэтому проверяйте именно то, что открывает ваш сервер. Это три базовые возможности сервера; в нашем примере понадобится только инструмент.

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

Как создать MCP-сервер на Python для чтения статуса заказа

Поручите работу с протоколом официальному SDK, а в своём коде сосредоточьтесь на поиске заказа. Понадобятся Python 3.10 или новее, uv — менеджер Python-проектов из официального руководства — и Node.js для Inspector. Текущая версия Inspector требует Node 22.19.0 или новее.

В терминале выполните команды по порядку:

1. uv init orders-mcp
2. cd orders-mcp
3. uv venv
4. uv add "mcp[cli]==2.3.0"

Создайте в этой папке файл orders.py и вставьте готовый код сервера. Все записи в примере вымышлены и предназначены для обучения. Здесь нет имён клиентов, платёжных данных или учётных данных для API.

import json

from mcp.server import MCPServer

mcp = MCPServer("orders")

# Fictional training data. No customer records or credentials.
ORDERS = {
    "A100": {"status": "shipped", "carrier": "Demo Courier"},
    "A101": {"status": "packing", "carrier": "not assigned"},
}


@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up a fictional order by ID, such as A100. Read-only.

    Args:
        order_id: Exact order ID, for example A100 or A101.
    """
    key = order_id.strip().upper()
    order = ORDERS.get(key)
    if order is None:
        return json.dumps({"found": False, "order_id": key})
    return json.dumps({"found": True, "order_id": key, **order})


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

Пример использует описанную в руководстве связку MCPServer, @mcp.tool() и mcp.run(transport="stdio"), но вместо инструментов для погоды проверяет заказ. Аннотация строкового типа сообщает SDK, что order_id — обязательный текстовый аргумент. Строка документации объясняет клиенту, когда пригодится инструмент. SDK создаёт описание инструмента и обрабатывает сообщения протокола.

Запустите uv run orders.py. Если процесс ничего не выводит и ждёт ввода, это нормально. stdio, стандартный ввод и вывод, служит каналом связи клиента с этим процессом. Остановите сервер, запущенный вручную, прежде чем позволить клиенту запустить собственную копию.

Не пишите журналы приложения в стандартный вывод. Используйте модуль Python logging: по умолчанию он направляет сообщения в стандартный поток ошибок. Случайный print() может повредить поток сообщений протокола. Это документированное ограничение stdio, а не вопрос оформления логов.

Когда замените словарь базой данных, сохраните такой же узкий интерфейс. Используйте параметризованный запрос, учётную запись БД с правами только на чтение нужных полей и проверяйте права вызывающего пользователя перед возвратом записи. Для этой задачи не принимайте от модели произвольный SQL-запрос.

Как проверить сервер в MCP Inspector

Сначала убедитесь, что инструмент работает, и только потом поручайте его модели. Из папки проекта выполните uv run mcp dev orders.py. Команда разработки SDK запустит MCP Inspector. Откройте в браузере URL, который выведет команда, и подключите сервер, если он ещё не подключён.

В разделе Tools выберите lookup_order. В форме должно появиться обязательное поле order_id. Вызовите инструмент с A100: результат должен содержать found: true, status: shipped и carrier: Demo Courier. Для A101 должен вернуться статус packing. Для DOES-NOT-EXIST результат должен содержать found: false.

Также отправьте запрос без order_id. Он должен завершиться ошибкой проверки входных данных, не запуская поиск заказа. Разделы Protocol и Console в Inspector помогут отличить некорректный запрос от сбоя серверного процесса.

Для повторяемой проверки из терминала используйте npx @modelcontextprotocol/inspector --cli uv run orders.py --method tools/list. Чтобы вызвать инструмент, выполните npx @modelcontextprotocol/inspector --cli uv run orders.py --method tools/call --tool-name lookup_order --tool-arg order_id=A100. Это команды из документации Inspector CLI.

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

Как подключить MCP в Claude Code и Cursor

Каждый локальный клиент запускает собственный процесс сервера. Держать Inspector открытым не нужно. Указывайте абсолютные пути: тогда запуск не будет зависеть от папки, которую открыл клиент.

Claude Code: выполните claude mcp add --transport stdio --scope local orders -- /ABSOLUTE/PATH/orders-mcp/.venv/bin/python /ABSOLUTE/PATH/orders-mcp/orders.py. В Windows интерпретатор находится по пути .venv\Scripts\python.exe. Команда соответствует синтаксису подключения локального сервера в Claude Code, включая разделитель -- перед командой запуска.

Проверьте подключение командой claude mcp get orders. В сессии Claude Code откройте /mcp, затем попросите: «Используй lookup_order для проверки A100. Сообщи только статус и перевозчика из результата». Проверьте вызов инструмента и переданные аргументы.

Cursor: создайте в проекте файл .cursor/mcp.json. Добавьте этот JSON, заменив оба абсолютных пути: {"mcpServers":{"orders":{"type":"stdio","command":"/ABSOLUTE/PATH/orders-mcp/.venv/bin/python","args":["/ABSOLUTE/PATH/orders-mcp/orders.py"]}}}.

Откройте Customize, включите сервер и задайте тот же вопрос в Agent. Проверьте вызов в соответствии с вашими настройками подтверждения действий. Путь к файлу, поля запуска и элементы управления описаны в документации MCP для Cursor. Если подключение не удалось, сначала проверьте путь к исполняемому файлу и stderr сервера, а затем меняйте инструмент.

Что выбрать: локальный stdio или удалённый HTTP

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

Удалённому сервису также нужен сетевой доступ к данным компании. Публикация адреса сама по себе не делает закрытую базу доступной и не настраивает правильные права.

В HTTP-протоколе 2026-07-28 каждый запрос самодостаточен. Актуальный Python SDK умеет обслуживать и старые клиенты: при добавлении реплик их сессиям может понадобиться закрепление маршрута за одной репликой. Перед масштабированием осознанно настройте документированные параметры совместимости; не исходите из того, что все подключённые клиенты используют последнюю редакцию протокола.

Как перевести проверку заказов на HTTP с авторизацией

Защитите HTTP-доступ токенами, выданными именно для этого сервиса. В спецификации MCP используется механизм авторизации OAuth 2.1: провайдер идентификации выполняет вход пользователя и выдаёт токен, а MCP-сервер проверяет его. Область доступа (scope) — это именованное разрешение, например orders:read. Аудитория (audience) указывает, какой сервис вправе принять токен.

SDK предоставляет интеграцию сервера ресурсов, а не систему входа вашей компании. Для этого примера настройте провайдер идентификации: автоматическое обнаружение параметров OAuth, регистрацию выбранных клиентов, PKCE для входа пользователя и адрес интроспекции токенов. PKCE подтверждает, что вход завершает то же приложение, которое его начало. Интроспекция запрашивает у издателя токена, активен ли он и какие действия разрешает.

Этот адаптер ожидает интроспекцию по HTTPS с аутентификацией клиента через HTTP Basic и ответом, содержащим active, aud, exp, client_id и scope. Настройте издателя так, чтобы в aud попадал точный публичный URL этого сервиса, а токены включали orders:read. Если ваш провайдер использует другой способ аутентификации при интроспекции, измените запрос по его документации. Если вместо этого он выдаёт JWT — подписанные токены, — реализуйте проверку подписи, издателя, срока действия и аудитории через тот же интерфейс TokenVerifier.

Добавьте uvicorn командой uv add uvicorn, затем создайте remote.py рядом с orders.py. Код следует официальному примеру интроспекции SDK и документированным интерфейсам HTTP и авторизации. Он использует уже проверенную функцию поиска заказа.

import os
import time
from urllib.parse import urlsplit

import httpx2
from pydantic import AnyHttpUrl

from mcp.server import MCPServer
from mcp.server.auth.provider import AccessToken, TokenVerifier
from mcp.server.auth.settings import AuthSettings
from mcp.server.transport_security import TransportSecuritySettings
from orders import lookup_order as local_lookup

RESOURCE = os.environ["MCP_RESOURCE_URL"]
ISSUER = os.environ["MCP_ISSUER_URL"]
INTROSPECT = os.environ["MCP_INTROSPECTION_URL"]
if any(urlsplit(url).scheme != "https" for url in (RESOURCE, ISSUER, INTROSPECT)):
    raise ValueError("Public auth and resource URLs must use HTTPS")


class OrderTokenVerifier(TokenVerifier):
    async def verify_token(self, token: str) -> AccessToken | None:
        try:
            async with httpx2.AsyncClient(timeout=5.0) as client:
                response = await client.post(
                    INTROSPECT,
                    data={"token": token},
                    auth=(os.environ["MCP_INTROSPECTION_CLIENT_ID"],
                          os.environ["MCP_INTROSPECTION_CLIENT_SECRET"]),
                )
                response.raise_for_status()
                data = response.json()
            audiences = data.get("aud", [])
            if isinstance(audiences, str):
                audiences = [audiences]
            expiry = data.get("exp")
            if (data.get("active") is not True or RESOURCE not in audiences
                    or not isinstance(expiry, int) or expiry <= time.time()):
                return None
            if data.get("iss", ISSUER) != ISSUER:
                return None
            return AccessToken(
                token=token, client_id=data["client_id"],
                scopes=data.get("scope", "").split(), expires_at=expiry,
                resource=RESOURCE, subject=data.get("sub"),
            )
        except Exception:
            return None


mcp = MCPServer(
    "orders",
    token_verifier=OrderTokenVerifier(),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl(ISSUER),
        resource_server_url=AnyHttpUrl(RESOURCE),
        required_scopes=["orders:read"], validate_token_resource=True,
    ),
)


@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up a fictional order by ID, such as A100. Read-only."""
    return local_lookup(order_id)


hostname = urlsplit(RESOURCE).hostname
security = TransportSecuritySettings(
    allowed_hosts=[hostname, f"{hostname}:*"],
    allowed_origins=[os.environ["MCP_ALLOWED_ORIGIN"]],
)
app = mcp.streamable_http_app(transport_security=security)

Задайте эти значения в окружении развёртывания или в хранилище секретов:

Список разрешённых хостов задан явно: иначе SDK по умолчанию принимает localhost, а публичное имя хоста отклоняет с ответом 421 Misdirected Request. Для браузерных origin действует отдельная проверка; перечисляйте только те, которыми действительно пользуетесь. Возвращаемое приложение уже включает обработку запуска и завершения работы. Эти детали описаны в документации по развёртыванию SDK и по ASGI-приложению. ASGI — интерфейс, через который Python-веб-серверы запускают такое приложение.

Запустите его за HTTPS-прокси вашей платформы командой uv run uvicorn remote:app --host 0.0.0.0 --port 8000. Публичный URL ресурса остаётся HTTPS, даже если прокси обращается к процессу по HTTP. Настройте доверие к заголовкам прокси в соответствии с границей доверия вашей платформы.

Прежде чем подключать реальные записи, выполните проверки по HTTP:

• Нет токена, токен просрочен или предназначен для другой аудитории: доступ отклоняется.
• Токен действителен, но не содержит orders:read: доступ отклоняется.
• Токен действителен, аудитория и область доступа верны: lookup_order возвращает демонстрационный статус.
• /.well-known/oauth-protected-resource/mcp: метаданные указывают правильный ресурс и издателя.

Используйте npx @modelcontextprotocol/inspector --server-url https://orders.example.com/mcp --transport http, чтобы проверить развёрнутый сервис и пройти его процедуру аутентификации. Тест инструмента в памяти обходит HTTP-авторизацию, поэтому не подтверждает работу этой границы доступа.

Для Claude Code добавьте отдельное подключение командой claude mcp add --transport http orders-remote https://orders.example.com/mcp, затем пройдите аутентификацию через /mcp. В Cursor добавьте удалённую запись в mcpServers с "url":"https://orders.example.com/mcp" и завершите вход через OAuth. Для заранее зарегистрированных клиентов Cursor также описывает объект auth с CLIENT_ID и scopes. Зарегистрируйте у издателя токенов нужные адреса обратного вызова клиентов. См. аутентификацию в Claude Code и настройку удалённого OAuth в Cursor.

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

Где разместить сервер: Render или Cloudflare Workers

Для Python-сервера из этого руководства я бы начал с Render. Веб-сервис на Python позволяет использовать уже созданное приложение. Cloudflare Workers тоже хорошо подходит, если вы готовы реализовать тот же узкий инструмент через документированный обработчик Worker.

Ниже — опубликованные провайдерами цены, проверенные 7 октября 2026 года:

Источники: цены Cloudflare Workers и цены Render. Если выбрать командные функции рабочего пространства Pro в Render, оно добавит $25/месяц к стоимости вычислительных ресурсов. Хранилище, сервисы идентификации, использование моделей и прочие дополнения нужно учитывать отдельно: здесь приведены цены хостинга, а не полная стоимость рабочего процесса с ИИ.

Развёртывание на Render: разместите orders.py, remote.py и requirements.txt в своём репозитории. В файл зависимостей добавьте mcp[cli]==2.3.0 и uvicorn, каждый на отдельной строке. Создайте Python Web Service, задайте команду сборки pip install -r requirements.txt и команду запуска uvicorn remote:app --host 0.0.0.0 --port $PORT. Добавьте переменные окружения из таблицы выше, а в MCP_RESOURCE_URL укажите выданное имя хоста или свой домен. Так документированный способ развёртывания Python-веб-сервиса на Render адаптируется к ASGI-приложению SDK.

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

Развёртывание на Cloudflare: используйте актуальную документацию обработчика MCP и руководство по удалённому серверу. Текущая реализация на TypeScript использует createMcpHandler из agents/mcp/server вместе с @modelcontextprotocol/server. Перенесите туда тот же поиск заказа и настройте аутентификацию, прежде чем делиться URL. Команда запуска Python uvicorn предназначена для Python-хостинга; для развёртывания Worker она не подходит.

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

Дайте серверу только тот доступ, который нужен его инструменту. Для проверки статуса заказа это учётные данные с правами только на чтение, выбранные поля и проверка разрешений на каждую запись. Возвраты денег, отмены заказов и изменения адреса вынесите в отдельные инструменты с отдельными правами. Аргументы, которые выбрала модель, никогда не заменяют авторизацию.

Проверяйте у HTTP-токенов издателя, срок действия, аудиторию и область доступа. Используйте HTTPS и отдельные учётные данные для обращения сервера к внутреннему API. Рекомендации MCP по безопасности запрещают сквозную передачу токенов: токен, предъявленный вашему MCP-сервису, не становится автоматически учётными данными для системы заказов. При локальном stdio ограничьте права процесса, который запускает сервер, его окружение и доступ к файловой системе.

Записывайте в журнал подтверждённого вызывающего пользователя, название инструмента, ссылку на запись с необходимым скрытием чувствительных данных, результат, время выполнения и ID запроса. Не записывайте токены и полные данные клиентов. Для stdio направляйте логи в stderr, для HTTP — в систему журналирования хостинга. Текст из записей рассматривайте как данные: примечание внутри заказа не должно давать разрешение на другое действие.

Добавьте шлюз перед серверами, когда нескольким серверам или командам нужны общие правила идентификации, ограничения частоты запросов, сбор аудита или отзыв доступа. Шлюз может централизовать эти механизмы, но каждый бэкенд по-прежнему обязан правильно проверять права на записи. Выбор такого подхода разобран в нашем руководстве по MCP gateway.

Шесть сценариев: где польза появится быстрее

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

Экономику стоит считать по вашему рабочему процессу. Условный пример: 80 проверок в день по 2 минуты занимают 160 минут. Если дальнейшие измерения покажут, что подключённый сценарий экономит 1 минуту на проверку, это вернёт 80 минут в день. Это арифметика, а не показатель производительности. Прежде чем заявлять об окупаемости хостинга, измерьте правильность ответов и сэкономленное время.

Две идеи для продукта

Самая перспективная идея — адаптер данных о заказах для команд поддержки. Команда могла бы купить узкую интеграцию, которая подставляет нужные сведения о доставке в уже используемый ассистент. По оценке DataForSEO, запрос “customer support automation” получает 260 поисков в Google в США в месяц; данные проверены 7 октября 2026 года. Это интерес к задаче в целом, а не число покупателей MCP. Intercom публикует цену Fin $0.99 за результат: у автоматизации поддержки уже есть бюджет, а небольшой адаптер добавляет контекст, не заменяя этот продукт.

Минимальная версия, которую можно продавать, могла бы включать одну систему заказов, lookup_order, вход с ограниченными правами, журнал аудита и черновик ответа со ссылками на возвращённые поля. Её преимущество — соответствие данным и правилам доступа конкретной компании. Но у существующих поставщиков уже может быть нужный коннектор, а доступ к моделям для команды, очистка данных и поддержка тоже стоят денег. Проверьте этот пробел с руководителем поддержки, прежде чем добавлять новые инструменты.

Вторая идея — поиск по правилам компании с учётом прав доступа. Специалист мог бы открыть доступ к утверждённым документам одной компании через ресурсы или узкий поисковый инструмент. По оценке DataForSEO, запрос “enterprise search” получает 390 поисков в месяц в США; данные проверены в ту же дату. MVP мог бы включать одну коллекцию документов, ссылки на источники, проверку актуальности и фильтрацию по правам вошедшего пользователя. Сложность в том, что сам продукт — это качество поиска и контроль доступа; просто обернуть папку в MCP легко повторить. Объём поиска показывает интерес к более широкой задаче, но не доказывает готовность платить за эту реализацию.

Какие задачи MCP не решает

MCP стандартизирует доступ. Качество данных, авторизация, надёжность бэкенда и выбор действий инструмента остаются вашей ответственностью. Модель может неверно понять корректный результат, а подключённые клиенты — различаться по поддерживаемым возможностям и правилам подтверждения действий.

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

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

Если вы хотите заказать для команды разработку и эксплуатацию MCP-сервиса с доступом к данным компании, наша услуга по созданию ИИ-систем включает интеграцию и контроль доступа.