MCP-сервер: как начать с одного инструмента и не открыть лишнее
MCP-сервер даёт клиенту единый способ узнать об инструментах и вызвать их. Модель не подключается к серверу напрямую. Клиент получает список возможностей, превращает их в инструменты для модели, исполняет выбранный вызов и возвращает результат в диалог. Поэтому главный вопрос при разработке MCP не «как быстро добавить функцию», а «какое действие можно безопасно дать этому клиенту».
Коротко
Начните с одного инструмента только для чтения и явной схемы аргументов.
Локальный процесс и удалённый HTTP-сервис требуют разной модели доверия.
Права, лимиты и проверка входа принадлежат MCP-серверу, а не описанию инструмента.
Relay остаётся API для модели; MCP-клиент исполняет обращения к вашему серверу на своей стороне.
Где проходит граница между MCP и LLM API?
MCP описывает связь клиентского приложения с источником возможностей: файлами, внутренним сервисом, базой знаний или собственным API. LLM API получает от клиента описание инструментов и возвращает просьбу об их вызове. Клиент решает, что делать с этой просьбой, а MCP-сервер проверяет её по своим правилам.
Эта граница полезна. Вы можете поменять модель, не переписывая сервер инструментов. И наоборот, сервер не должен знать о внутреннем устройстве модели, чтобы проверять права пользователя. Клиент Claude Code подключается к Relay по инструкции интеграции, а инструменты получает из своей конфигурации MCP.
Некоторые клиенты умеют работать с пользовательским endpoint и MCP одновременно. Например, документация Relay для GitHub Copilot описывает выбор совместимого API и покрытие инструментов с MCP. Это не означает, что Relay запускает ваш MCP-сервер: сервер остаётся вашим процессом или вашим HTTP-сервисом.
С какого инструмента начать?
Выберите действие без побочного эффекта. Хороший первый кандидат: найти документ, показать статус задачи для текущего пользователя или прочитать разрешённую настройку. Не начинайте с удаления файлов, перевода денег, изменения доступа или выполнения произвольной команды.
У инструмента должны быть короткое имя, понятное описание и жёсткая схема аргументов. В описание включайте границы: когда инструмент использовать можно, когда нельзя и что он вернёт. Сервер всё равно повторяет проверку. Модельный инструмент не превращает недоверенный ввод в доверенный.
Ниже показан минимальный контур на JavaScript с CommonJS-подключением. Версия SDK и первичный источник для примера записаны в README партии. Сам пример задаёт форму границы, но не готовую политику доступа.
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js')
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js')
const { z } = require('zod')
const server = new McpServer({ name: 'orders-read', version: '1.0.0' })
server.tool(
'find_order',
'Находит один заказ текущего пользователя по номеру.',
{ orderNumber: z.string().min(1).max(64) },
async ({ orderNumber }) => ({
content: [{ type: 'text', text: JSON.stringify({ orderNumber, status: 'unknown' }) }],
}),
)
server.connect(new StdioServerTransport())Фрагмент намеренно не ходит в настоящую базу. В реальном обработчике перед поиском появляется контекст аутентифицированного клиента, проверка разрешения и безопасное представление результата. Номер заказа без идентичности клиента не даёт права искать чужие данные.
Когда выбрать локальный процесс, а когда HTTP?
Локальный MCP-сервер подходит для работы с файлами разработчика или утилитой на его компьютере. Он запускается дочерним процессом клиента и наследует риск этого окружения. Ограничьте разрешённые каталоги и не принимайте путь как готовую команду оболочки.
Удалённый сервер нужен, когда инструментом пользуются несколько людей или он работает с общим сервисом. Тогда добавляются аутентификация, изоляция арендаторов, ограничение частоты и журнал действий. HTTP не делает сервер безопаснее автоматически. Он только переносит границу доверия в сеть.
Отдельно решите, какие операции доступны в каждом транспорте. Локальный клиент не должен получать привилегии общего production-сервиса лишь потому, что у него есть конфигурация MCP.
Как проверить вход и права?
Проверка состоит из трёх слоёв. Схема отсеивает неверные типы и лишние поля. Бизнес-проверка решает, существует ли объект и разрешено ли действие текущему субъекту. Наконец, исполнитель ограничивает последствия: лимит строк, разрешённые поля, таймаут и предел выдачи.
Не доверяйте описанию инструмента и не доверяйте аргументам, пришедшим от модели. Модель может неверно понять текст пользователя, а пользователь может попытаться заставить её вызвать инструмент с чужим идентификатором. Для изменяющих операций используйте явное подтверждение человека или отдельный безопасный workflow.
Тот же принцип действует для function calling вне MCP. В статье о безопасности вызовов инструментов разобраны границы полномочий, журналы и опасные действия.
Какие журналы реально помогают?
На каждый вызов сохраняйте время, клиента, имя инструмента, итог проверки, безопасный идентификатор объекта и результат. Полное содержимое документов, токены авторизации и необработанные персональные данные в лог не попадают. Такие записи отвечают на практический вопрос: что именно сделал агент и от чьего имени.
Добавьте лимит числа вызовов на сессию и отдельно на инструмент. Если агент зациклился, сервер должен отказать предсказуемо, а не продолжать обращения к базе. В ответ модели возвращайте безопасное сообщение с причиной, без стек-трейса или конфигурации.
Если модель вызывается через Relay, сохраняйте и x-request-id. Он связывает запись MCP с API-вызовом, который потом можно найти в журнале запросов. Сам журнал Relay не заменяет аудит вашего инструмента: он не знает, какую операцию выполнил MCP-сервер.
Как подключить сервер к агенту?
Сначала запустите сервер в изолированном окружении и проверьте его вызовом без модели. Затем подключите его к одному клиенту, откройте перечень инструментов и выполните несколько заранее подготовленных сценариев: допустимый запрос, неверный аргумент, отказ в доступе, медленный внешний сервис. Только потом включайте модельный цикл.
Для Claude Code пригодятся навыки и постоянные инструкции, но они не заменяют серверную политику. Материал как создать skills для Claude Code поможет отделить инструкции агента от функций, которые он вправе вызвать. Описание доступных HTTP- и Messages-совместимых протоколов есть на странице протоколов Relay.
Выберите модель с совместимым протоколом и поддержкой инструментов из каталога. Не обещайте всем клиентам одинаковый набор возможностей: у каждого свои настройки, режимы авторизации и ограничения.
Что проверить перед подключением к рабочим данным?
Составьте небольшой набор сценариев. В нём нужны разрешённый вызов, попытка доступа к чужому объекту, пустой результат, превышение лимита, повтор одинакового запроса и отказ внешнего сервиса. Для каждого случая заранее определите безопасный ответ и событие в журнале.
Не передавайте в инструменты универсальный доступ «на всякий случай». Расширение разрешений должно быть отдельным изменением с собственным разбором рисков. Один узкий инструмент, который работает предсказуемо, ценнее набора широких функций, к которым никто не готов применить аудит.
Чем tools отличаются от resources и prompts?
Инструмент выполняет действие по запросу клиента: ищет запись, запускает проверку или меняет состояние. Ресурс отдаёт читаемые данные по известному адресу. Prompt предоставляет шаблон для повторяющейся работы. Эти примитивы не стоит смешивать ради простоты кода.
Справочник, который модель читает без параметров, может быть ресурсом. Поиск по документам с фильтром прав лучше сделать инструментом, потому что серверу надо проверить, кто и что запросил. Шаблон для разбора инцидента остаётся prompt, пока он не запускает доступ к данным. Такое разделение делает аудит и права заметнее.
Не публикуйте секреты как ресурс. Клиент может передать содержимое ресурса модели, а модель включит часть текста в ответ. Ресурсы требуют того же обзора доступа, что и обычный API, даже если они кажутся статическими и внутренними.
Как развернуть удалённый сервер без общего ключа?
Каждый клиент должен проходить аутентификацию как отдельный субъект. Сервер извлекает идентичность из проверенного механизма, назначает разрешения и применяет лимит для этого субъекта. Общий административный ключ в конфигурации клиентов ломает отзыв доступа и делает аудит бесполезным.
Разделите технический доступ сервера к внутренним системам и права конечного пользователя. Сервер может иметь соединение с базой, но запрос пользователя получает только строки своей организации. Внешнему сервису передавайте минимальные полномочия, которые нужны конкретному инструменту. Ротация и отзыв должны проверяться без перезапуска каждого клиента.
Перед публичным HTTP-развёртыванием нагрузите сервер сценариями с медленным ответом, обрывом соединения и повтором запроса. Убедитесь, что таймаут освобождает ресурсы, а повтор не создаёт второй необратимой операции. Это проверка сервера, а не модели.
Нужен ли MCP, если уже есть function calling?
Не всегда. Прямой function calling удобен, когда один сервис нужен одному приложению. MCP оправдан, когда один и тот же набор инструментов должны открывать разные совместимые клиенты. В обоих случаях проверка входа, прав и последствий остаётся серверной обязанностью.
Можно ли вернуть модели весь текст внутреннего документа?
Только если этот документ разрешён текущему пользователю и действительно нужен для задачи. Ресурс или результат инструмента может попасть в контекст и далее в ответ. Ограничивайте поля, длину результата и область поиска, а чувствительные данные передавайте через отдельный безопасный контур.
Как остановить зациклившийся агентный вызов?
Держите счётчик на стороне MCP-сервера и ограничивайте время работы инструмента. При повторе с теми же аргументами или достижении предела верните безопасную ошибку и завершите задачу. Модель не должна получать возможность бесконечно повторять сетевой запрос.