Локальный MCP-сервер: создать, подключить и проверить вызов

Что делает локальный MCP-сервер?

MCP-сервер объявляет инструменты с именем, описанием и схемой аргументов; клиент может получить перечень через tools/list, затем отправить tools/call с конкретными аргументами. Это интерфейс к функции, а не гарантия, что языковая модель её вызовет. В SDK декоратор @mcp.tool() строит схему из типов функции, а её строка документации становится описанием инструмента. s3 s7

Для одного компьютера проще начать со stdio: MCP-клиент сам запускает Python-файл дочерним процессом и обменивается сообщениями через stdin/stdout. Порт не открывается. В HTTP-варианте сервер слушает отдельный адрес; он нужен для клиентов вроде Open WebUI, которые подключаются к удалённому MCP endpoint. Не пытайтесь вводить stdio-команду как URL /mcp: это два разных транспорта. s2 s5 s8 s6

Маршрут задачи: безопасный тестовый инструмент → stdio-сервер → Inspector → зафиксированный ответ → при необходимости локальная модель и её host. Если задача — корпоративные файлы или учётные данные, не заменяйте проверку безопасности безвредным тестом: реальному инструменту потребуются собственные права, ограничение действий и журнал. Спецификация рекомендует человеческое подтверждение для операций, но не заставляет каждый клиент его предоставлять. s7

Что подготовить до запуска?

Документация SDK v2 указывает Python 3.10+ и установку mcp[cli]. Для Inspector потребуется установленный Node.js с npx; mcp dev запускает интерактивный Inspector, а CLI Inspector тоже использует npx. Сначала проверьте зависимости в отдельном пустом учебном каталоге и не запускайте непроверенный сервер там, где есть рабочие секреты. Ни одна команда ниже не загружает веса модели, но установка SDK и Inspector получает пакеты из внешних реестров. s1 s2 s4

mkdir mcp-local-smoke && cd mcp-local-smoke
uv init
uv add "mcp[cli]"

Эти команды описывают учебное окружение с uv, а не установленный нами проект. Сохраняйте нижеуказанный server.py именно в созданном каталоге. Для воспроизводимости в рабочем контуре отдельно фиксируйте версии зависимостей и источник пакетов. s1 s6

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

В отличие от универсального файлового сервера этот пример не имеет инструментов чтения или записи: он возвращает переданную короткую метку. Его основа — официальный MCPServer, декоратор @mcp.tool() и запуск mcp.run() с транспортом по умолчанию stdio. Ограничение длины метки — наша проектная мера для теста, не свойство протокола. s1 s2 s3

from mcp.server import MCPServer

mcp = MCPServer("Local-Smoke")

@mcp.tool()
def echo_marker(marker: str) -> str:
"""Return a short test marker; do not access files or the network."""
if not marker.isascii() or not marker.isalnum() or len(marker) > 24:
return "invalid_marker"
return f"tool_called:{marker}"

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

Пустой marker тоже не годится для осмысленного теста: используйте, например, smoke28a, затем другую метку smoke28b. Функция не читает файл, не обращается к API и не принимает команду на исполнение; проверка аргумента выполняется перед ответом. Этот учебный пример не даёт разрешения добавлять действия с письмами, документами, терминалом или 1С по аналогии без отдельной политики. s3 s7

Как убедиться, что сервер отвечает по протоколу?

Официальный SDK предлагает uv run mcp dev server.py: команда запускает Inspector и сообщает адрес тестового интерфейса. В его вкладке Tools должен появиться echo_marker; вызовите его с marker=smoke28a и сравните результат с tool_called:smoke28a. Затем вызовите с marker=smoke28b и убедитесь, что значение изменилось. Увидеть список недостаточно: нужен отдельный фактический результат tools/call. s1 s2 s4 s7

uv run mcp dev server.py

Inspector CLI из официального репозитория допускает вызов tools/list и tools/call у локального stdio-процесса. Если нужен машинно читаемый журнал вместо формы, запустите команды из каталога проекта; npx загрузит Inspector, а абсолютные пути устраняют зависимость от его рабочего каталога. Выберите учебное окружение и проверьте, что в ответе инструмента есть метка; не трактуйте напечатанную моделью фразу как протокольный ответ. s4 s6

npx @modelcontextprotocol/inspector --cli "$(pwd)/.venv/bin/python" "$(pwd)/server.py" --method tools/list
npx @modelcontextprotocol/inspector --cli "$(pwd)/.venv/bin/python" "$(pwd)/server.py" --method tools/call --tool-name echo_marker --tool-arg marker=smoke28a

Строки выше описывают Unix-подобную систему, где uv создал .venv в текущем каталоге; на Windows путь к Python другой. MCP Inspector — клиент, его прямой вызов тестирует протокол без языковой модели. Отдельно можно проверить функцию в памяти, но такой тест не доказывает, что конкретный host сумеет стартовать дочерний процесс или что выбранная модель корректно вызовет инструмент. s4 s6

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

После прямого теста в настройке MCP-клиента укажите команду и абсолютный путь к этому файлу. В официальной инструкции Python SDK один и тот же запуск uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py служит основой для Claude Desktop, Claude Code и IDE, но формат конфигурации у каждой программы свой. Для VS Code документация показывает servers с type: stdio, а для Cursor — mcpServers; не копируйте чужой JSON в неподходящий клиент. Хост может не наследовать ваш PATH и переменные окружения, поэтому проверяйте реальный исполняемый файл и не вписывайте секреты прямо в публичную конфигурацию. s6

Критерий реального вызова модели: после запроса о метке в трассе клиента присутствуют tools/call, имя echo_marker, отправленный аргумент и точный ответ инструмента; ответ модели согласуется с ним. Если виден только гладкий текст без вызова, сервер может работать исправно, а проблема быть в доступе инструмента, режиме клиента либо способности модели к tool calling. Для выбора модели, runtime и отдельной проверки переходите к гайду по вызову инструментов. s3 s7

Что делать, если команда не работает?

• Терминал «завис» после python server.py. Для stdio это ожидаемо: процесс ждёт протокольный запрос от клиента. Подключите Inspector, не проверяйте сервер HTTP-запросом к несуществующему порту. s2 s5
• Inspector не видит инструмент. Сначала проверьте каталог и точный путь к server.py, затем версию установленного SDK, наличие npx и ошибки запуска в stderr; не печатайте служебный текст в stdout до начала протокольного обмена. s1 s2 s5
• Список виден, вызов не проходит. Проверьте имя echo_marker, аргумент marker и сообщение об ошибке в ответе инструмента; SDK валидирует типы аргументов по схеме. Испытайте допустимую и заведомо недопустимую метки. s3 s7
• Inspector вызывает, но модель не вызывает. Разделите протокольный тест и тест модели: проверьте включён ли инструмент в клиенте, доступен ли контекст описания и сохранена ли трасса вызова. Само название инструмента в списке не подтверждает выполнение. s6 s7
• Open WebUI требует URL. Нативное подключение WebUI использует Streamable HTTP, а не stdio; SDK показывает переход на mcp.run(transport="streamable-http", port=3001) и адрес http://127.0.0.1:3001/mcp. Но открывать endpoint в рабочей сети без контроля доступа нельзя: сначала проверьте адрес, авторизацию, контейнерную маршрутизацию и периметр в отдельном гайде Open WebUI. s2 s5

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

Следующий шаг: проверить вызов инструмента выбранной локальной моделью, сохранив трассу клиента и ответ echo_marker. Это звено «инструмент → runtime/модель → проверяемый результат»; факт наличия MCP-сервера не означает, что его уже использовала модель. s3 s7