Что такое MCP? Как Model Context Protocol соединяет AI Agent, Tools, API и JSON Schema?

Симптом: разные AI Agent видят ваши API по-разному, а часть вызовов заканчивается ошибками параметров и небезопасными правами.
Самое быстрое решение: вынесите интеграцию в MCP Server, опишите каждый инструмент через JSON Schema, а выполнение, авторизацию и подтверждения оставьте под контролем Host и MCP Client.

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

Что именно соединяет MCP Model Context Protocol

MCP Model Context Protocol — открытый протокол для связи AI-приложений с инструментами, ресурсами и шаблонами подсказок. Это не модель, не облачный исполнитель и не замена Function Calling. В типичной архитектуре модель выбирает действие, но сетевое соединение, жизненный цикл процесса и политика безопасности находятся у Host-приложения.

Разделяйте четыре уровня:

• Host — основное AI-приложение или агентная платформа. Оно создаёт клиентов, управляет подключениями, показывает пользователю запросы на подтверждение и применяет политику доступа.
• MCP Client — компонент внутри Host, поддерживающий соединение с конкретным сервером. Обычно один Client обслуживает одно подключение к одному MCP Server.
• MCP Server — адаптер, который публикует инструменты, ресурсы или prompts. Он может быть локальным процессом или удалённым сервисом.
• API и внутренние системы — фактические базы данных, CI/CD, CRM, файловые хранилища, сервисы автоматизации или команды операционной системы.

Официальная архитектура MCP описывает Host как компонент, который создаёт и управляет Client-подключениями. Это важное разграничение: модель обычно не устанавливает сетевое соединение с MCP Server самостоятельно.

Главная ошибка при проектировании — считать, что модель напрямую «подключается к API». На практике модель получает доступные описания инструментов в контексте, предлагает вызов, а Client передаёт его серверу. MCP задаёт общий формат обмена, но не решает за вас вопросы бизнес-логики, лимитов внешнего API, изоляции секретов или допустимого уровня риска.

Сквозная схема одного вызова

sequenceDiagram
    participant U as Пользователь
    participant H as Host
    participant M as Модель
    participant C as MCP Client
    participant S as MCP Server
    participant A as Внутренний API

    U->>H: Запрос на действие
    H->>C: Запуск или выбор подключения
    C->>S: initialize и обмен возможностями
    C->>S: tools/list
    S-->>C: tools + inputSchema + outputSchema
    C->>M: Доступные инструменты и описания
    M-->>H: Предложение tools/call
    H->>C: Проверка политики и подтверждение
    C->>S: tools/call с аргументами
    S->>A: Реальный API-запрос
    A-->>S: Данные или ошибка
    S-->>C: Результат инструмента
    C-->>H: Результат для модели
    H-->>M: Обновлённый контекст
    M-->>U: Ответ или следующий шаг

На этой схеме MCP, Function Calling и фактическое выполнение API находятся на разных уровнях:

1. MCP описывает, как Client и Server обмениваются сообщениями и возможностями.
2. Function Calling позволяет модели сформировать предложение вызвать функцию с аргументами.
3. Реальный API-вызов выполняется внутри обработчика MCP Server.

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

Первый этап: Host и Client запускают MCP Server

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

Один Client может работать только с tools, другой — также с resources, prompts, уведомлениями или отдельными расширениями. Поэтому MCP Server не должен предполагать наличие конкретной функции только потому, что она описана в общей спецификации. Проверяйте negotiated capabilities и тестируйте фактическое поведение каждого совместимого клиента.

Для запуска есть два основных варианта.

Вариант	Как устанавливается связь	Сильные стороны	Ограничения и эксплуатационные издержки
Локальный STDIO	Host запускает MCP Server как дочерний процесс и обменивается JSON-RPC через стандартные потоки	Простая изоляция, нет публичного endpoint, удобно для личных инструментов	Зависимость от локальной среды, сложнее общий доступ и централизованный аудит
Удалённый Streamable HTTP	Client отправляет сообщения на HTTP endpoint, сервер работает как отдельная служба	Общий доступ для команды, централизованные логи, прокси и независимый жизненный цикл	Нужны TLS, аутентификация, контроль Origin, мониторинг и защита от сетевых сбоев
Гибридный режим	Общие операции работают удалённо, чувствительные действия остаются локально	Можно разделить риски и зависимости	Две модели деплоя, разные политики секретов и больше сценариев отказа

Стандартные транспорты и требования к их поведению описаны в официальной документации MCP по транспортам. Транспорт определяет способ доставки сообщений, но не меняет смысл tools/list или tools/call.

Если вы начинаете с локального сервера, не публикуйте его напрямую в Интернет. Для локального HTTP-режима привязывайте службу к loopback-интерфейсу, проверяйте Origin и добавляйте аутентификацию. Это снижает риск сценария, при котором веб-страница или вредоносный процесс пытается использовать локальный MCP Server как незащищённый шлюз к файлам и командам.

Напоминание: переход с STDIO на HTTP — это не простая замена команды запуска на URL. Вы добавляете сетевой периметр, управление токенами, журналы доступа, правила повторов и новый класс ошибок.

Второй этап: Client обнаруживает инструменты и читает JSON Schema

После инициализации Client запрашивает список инструментов через tools/list. Каждая запись обычно содержит:

• уникальное имя;
• краткое назначение;
• описание параметров;
• inputSchema;
• при поддержке сервером — outputSchema;
• аннотации поведения и дополнительные метаданные.

MCP использует JSON Schema для описания структуры входных и выходных данных. Благодаря этому Client может проверить обязательные поля, типы, перечисления и отдельные ограничения до фактического вызова API. Однако поддержка отдельных ключевых слов схемы может отличаться между клиентами, поэтому проверка на сервере обязательна.

Пример инструмента для чтения статуса сборки:

{
  "name": "get_build_status",
  "description": "Возвращает статус сборки по идентификатору проекта",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Внутренний идентификатор проекта"
      },
      "environment": {
        "type": "string",
        "enum": ["test", "production"]
      }
    },
    "required": ["project_id", "environment"],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string"
      },
      "commit": {
        "type": "string"
      }
    },
    "required": ["status"]
  }
}

Здесь JSON Schema ограничивает типы и обязательные поля, но не гарантирует правильный выбор инструмента. На решение модели влияют также name и description. Название вроде run_admin_action слишком расплывчато и потенциально опасно: Agent может выбрать его вместо более узкой операции.

Разделите чтение журнала, повторный запуск задачи и удаление артефактов на самостоятельные инструменты. Описание должно объяснять:

• какое действие выполняется;
• какие системы оно изменяет;
• какие параметры обязательны;
• является ли операция только чтением;
• может ли она быть повторена без побочных эффектов;
• требуется ли подтверждение пользователя.

Учитывайте три ограничения:

1. inputSchema описывает контракт, но не заменяет серверную валидацию. Проверяйте права и значения повторно внутри обработчика.
2. outputSchema помогает структурировать ответ, но часть клиентов может его игнорировать.
3. При объединении нескольких серверов возможны одинаковые имена инструментов. Client или Host должен добавлять префикс сервера либо другой механизм устранения коллизий.

Третий этап: MCP Server выполняет вызов и возвращает результат

Когда пользователь просит проверить сборку, модель получает описания доступных инструментов и предлагает вызов get_build_status с объектом аргументов. До выполнения Host должен решить, разрешено ли это действие текущему пользователю, проекту и среде.

Затем Client отправляет tools/call. MCP Server выполняет последовательность:

1. разбирает JSON-RPC-сообщение;
2. находит обработчик по имени инструмента;
3. валидирует аргументы по inputSchema;
4. проверяет токен, область доступа и бизнес-права;
5. преобразует параметры в запрос к фактическому API;
6. ограничивает время ожидания и число повторов;
7. нормализует ответ;
8. возвращает результат или ошибку выполнения.

Ошибки протокола и ошибки выполнения нужно различать. Неверное имя инструмента или повреждённая структура запроса относятся к JSON-RPC-ошибкам. Ошибка API, недопустимый идентификатор проекта или отказ по бизнес-правилу могут вернуться как результат инструмента с признаком ошибки, чтобы модель могла скорректировать параметры.

Официальное описание MCP-инструментов и вызовов показывает, как сервер объявляет tools и возвращает результаты. При этом конкретная форма обработки ошибок всё равно должна быть согласована с вашим клиентом и внешним API.

Не делайте бесконечный цикл «ошибка — повтор — ошибка». Для каждого инструмента задайте:

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

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

Сценарий: инструмент запускает сборку

Представьте внутренний MCP Server, который открывает Agent доступ к CI/CD. Пользователь просит запустить сборку ветки. Модель предлагает имя инструмента и параметры, но не должна самостоятельно получать служебный токен.

Host проверяет:

• имеет ли пользователь право запускать сборку;
• разрешена ли выбранная ветка;
• требуется ли ручное подтверждение;
• не выполняется ли уже такая же задача;
• можно ли отправить запрос в production-среду.

После подтверждения Client передаёт вызов серверу. MCP Server создаёт задачу в CI/CD, получает идентификатор запуска и возвращает короткий структурированный результат. Затем отдельный инструмент может проверить статус. Такой дизайн лучше, чем один вызов, который блокируется до завершения длительной сборки и заставляет Agent повторять запросы без контроля.

Как распределить права и секреты

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

Разделите доступ минимум на три группы:

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

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

В удалённом режиме MCP Server выступает как защищённый ресурс, а Client получает доступ через транспортный уровень. Для HTTP-сценариев используйте TLS, проверяемые токены, ограниченные области доступа и отдельную авторизацию для внешнего API. Не передавайте полученный токен во внешний сервис без проверки: контекст доступа к MCP Server и credentials downstream-системы могут иметь разные права.

Официальные требования MCP к авторизации требуют проверять токены до обработки запроса и не возвращать данные неавторизованному субъекту. На практике это означает, что проверка должна находиться на серверной стороне, а не только в интерфейсе Host или в описании инструмента.

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

1. Кто может видеть инструмент?
2. Кто может вызвать его автоматически?
3. Какие параметры требуют подтверждения?
4. Какой секрет используется при выполнении?
5. Что попадёт в журнал и как долго будет храниться?

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

Как перенести локальный MCP Server в удалённый сервис

Переход к удалённому режиму лучше выполнять поэтапно.

Шаг 1. Отделите обработчики от процесса запуска

Код, который выполняет запросы к API, не должен зависеть от STDIO. Вынесите бизнес-операции в отдельный слой, чтобы транспорт можно было заменить без переписывания логики.

Шаг 2. Добавьте HTTP-транспорт

Разместите MCP Server за TLS и обратным прокси. Проверьте передачу JSON-RPC-сообщений, заголовков, потоковых ответов и сообщений об ошибках. Убедитесь, что прокси не обрезает соединение во время длительной операции.

Шаг 3. Перенесите секреты в контролируемое окружение

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

Шаг 4. Включите аутентификацию и аудит

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

Шаг 5. Проверьте ошибки и отмену

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

Шаг 6. Сравните локальную и удалённую среду

Зафиксируйте версии SDK, MCP Server, Client и зависимостей. Затем повторите initialize, tools/list, успешный tools/call, ошибочный вызов и сценарий отказа. Для дополнительной проверки можно использовать официальный набор conformance-тестов MCP, но результаты нужно сверять с тем подмножеством возможностей, которое реально поддерживает ваш клиент.

Как выбрать локальную, удалённую или гибридную архитектуру

Используйте следующие условия принятия решения:

• Если инструмент работает только с файлами, локальным Git, IDE или пользовательским окружением, выбирайте STDIO. Не выносите его в Интернет только ради единообразия.
• Если один MCP Server должен обслуживать несколько пользователей и Agent-платформ, выбирайте Streamable HTTP. Сразу закладывайте авторизацию, аудит, лимиты и независимый жизненный цикл.
• Если API требует общего доступа, а чувствительные действия завязаны на локальную машину, выбирайте гибрид. Общие операции чтения можно разместить удалённо, а команды с физическими ключами, IDE или локальными сертификатами оставить рядом с исполнителем.
• Если операция длится дольше допустимого HTTP-соединения, используйте отдельную модель задач только после проверки поддержки у обеих сторон. Иначе применяйте собственный job-id в контракте инструмента.
• Если нужен постоянный доступ к Xcode, подписи приложений или автоматизации macOS, сначала подтвердите физические и программные зависимости. Для обычного REST API Mac не требуется.

При выборе инфраструктуры учитывайте не только вычислительную мощность. Для удалённого MCP Server важнее стабильность процесса, сетевой маршрут до API, хранение сертификатов, перезапуск после сбоя и доступ команды к журналам. Если MCP-инструменты должны постоянно обращаться к macOS-ресурсам, заранее изучите инфраструктуру Kvmjet и требования к удалённому подключению.

Частые ошибки перед вводом в эксплуатацию

Универсальный инструмент с широкими правами.
execute_command, call_api или admin_action выглядят удобно, но делают выбор модели слишком рискованным. Разбивайте операции по назначению и уровню воздействия.

Доверие только к JSON Schema.
Schema проверяет структуру, но не знает, имеет ли конкретный пользователь право удалить запись или запустить production-сборку. Серверная авторизация обязательна.

Секреты в описании инструмента.
Описание может попасть в контекст модели, журнал, интерфейс отладки или трассировку. Credentials должны оставаться в Host, защищённом окружении или менеджере секретов.

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

Предположение, что все клиенты поддерживают весь MCP.
Совместимость нужно проверять по capabilities, версиям SDK и реальным тестовым вызовам. Не переносите поведение одного продукта на весь протокол.

Развёртывание на Mac без причины.
MCP не требует macOS сам по себе. Mac оправдан, когда инструмент зависит от Xcode, подписи, симулятора, AppleScript или другого окружения Apple. Для стандартных API удалённый Linux-сервис часто будет проще.

Когда удалённый Mac действительно нужен MCP Server

Если ваши инструменты обращаются к обычной базе данных, HTTP API или CI/CD, разворачивать MCP Server именно на Mac не нужно. Linux или обычный сервер часто проще администрировать, легче изолировать по сетевым политикам и удобнее масштабировать.

Другая ситуация возникает, когда MCP-инструмент должен постоянно обращаться к Xcode, сертификатам подписи, симуляторам, AppleScript или другим ресурсам macOS. Локальная машина разработчика создаёт реальные ограничения: она может быть выключена, занята другим процессом, недоступна команде и содержать непредсказуемую версию окружения.

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

В таких условиях аренда удалённого Mac через Kvmjet может быть практичнее: вы получаете отдельную среду для проверки MCP Server, доступа к macOS-инструментам и командной автоматизации без привязки к рабочему ноутбуку. Перед обращением проверьте длительность нагрузки, требования к подписанию, сетевой доступ и способ хранения секретов; если нужен такой сценарий, используйте контактную форму Kvmjet.