Архитектура MCP для разработчиков: как связать ИИ с инструментами

Model Context Protocol (MCP) задаёт общий способ подключать ИИ-приложения к данным и действиям. Ценность протокола появляется тогда, когда разработчик продумывает границы доступа и поведение при ошибках, а не просто оборачивает API в инструмент.

Кто с кем разговаривает

Хост — приложение, в котором работает ассистент. MCP-клиент внутри хоста поддерживает соединение с сервером. Сервер предлагает возможности: инструменты для действий, ресурсы для чтения контекста и шаблоны запросов. Модель видит описание доступных инструментов, а хост выполняет выбранный вызов. Сервер не должен предполагать, что аргументы модели всегда верны или безопасны.

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

Пять решений перед первым сервером

1. Разделите области ответственности. Поиск по документам, бухгалтерские операции и публикация — разные границы риска. Не выдавайте всем задачам доступ ко всему набору действий.
2. Начните с малого набора инструментов. Название и описание должны объяснять, что делает инструмент, когда его вызывать, какие аргументы он принимает и что возвращает. Проверяйте, выбирает ли агент правильный инструмент на реальных задачах.
3. Ограничьте полномочия. Пользователь, проект и конкретное действие должны иметь нужные права. Доступ к чтению не означает право изменять или публиковать данные.
4. Храните состояние в подходящем источнике. База или внешняя система хранит долгоживущие данные; сервер не должен незаметно терять важное состояние при перезапуске.
5. Зафиксируйте конфигурацию проекта. Версионируйте несекретные настройки и инструкции запуска. Токены и ключи храните в предназначенном для этого секретном хранилище, а не в репозитории.

Пять рабочих схем

Один агент и несколько узких серверов

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

Серверы на уровне проекта

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

Несколько агентов с общими источниками

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

Передача идентичности пользователя

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

Ограничение объёма ответа

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

Семь частых ошибок

1. Логи в stdout при stdio. Этот поток занят сообщениями протокола; диагностические сообщения направляйте в stderr.
2. Непонятные имена. Инструмент get_data не объясняет, что именно он вернёт. Назовите действие и объект явно.
3. Слишком много инструментов. Удаляйте дубли и проверяйте, какие возможности действительно нужны на конкретном этапе.
4. Блокирующий ввод-вывод. Долгий синхронный вызов может задержать остальные запросы; используйте подходящие механизмы асинхронной работы и тайм-ауты.
5. Ошибки без контекста. Возвращайте понятную причину и безопасный следующий шаг, не раскрывая секреты и внутренние данные.
6. Неясные описания. Опишите результат, ограничения и побочные эффекты; проверяйте описание на задачах, которые агент должен решить.
7. Непроверенные аргументы. Проверяйте типы и разрешённые значения. Не собирайте команды оболочки из входа модели; при необходимости используйте аргументы процесса и ограниченную среду.

Безопасность и эксплуатация

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

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

Когда MCP не нужен

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

Как начать

Возьмите один сценарий чтения, например поиск по публичной документации. Опишите инструмент, подключите его к тестовому клиенту и проверьте корректные запросы и ошибки. Затем добавьте контроль доступа и наблюдаемость. Только после этого рассматривайте действия, меняющие данные. Актуальная спецификация и примеры доступны на официальном сайте MCP.