MCP-сервер: что это и как подключить инструменты к ИИ-агенту

MCP-сервер: что это и как подключить инструменты к ИИ-агенту Полезное

Агенту в IDE нужно читать файлы проекта, но ничего в них не менять, а позже — заводить задачи в трекере. Доступ при этом хочется ограничить: агент видит только папку проекта и не может записывать и удалять файлы. Подключить такие инструменты к агенту и ограничить их права позволяет MCP.

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

MCP-сервер — такая внешняя программа. Она выполняет действия в своей системе (файлах проекта, трекере задач, базе данных) и возвращает результат.

Сама модель ничего не вызывает: она только просит вызвать инструмент, а вызов исполняет приложение.

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

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

В статье два примера, и устроены они по-разному:

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

Четыре понятия, которые понадобятся дальше:

Понятие Что это В примерах
Хост приложение, где работает агент: IDE, CLI-агент, чат-клиент IDE
Клиент коннектор внутри хоста, связанный ровно с одним сервером по клиенту на каждый сервер
Сервер отдельная программа с инструментами и данными файловый сервер; в схеме — сканер и трекер
Инструмент функция сервера с названием, описанием и схемой параметров read_text_file; в схеме — scan_secrets и create_issue

Зачем агенту MCP

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

MCP часто путают с вызовом функций (function calling). Вызов функций — механизм модели и ее API: модель получает описания функций и отвечает JSON с тем, какую вызвать и с какими аргументами.

MCP — протокол между приложением и сервером, который этот инструмент предоставляет и исполняет. Они дополняют друг друга, а не заменяют.

С навыками агента MCP тоже не совпадает. MCP-сервер — работающая программа с API, которая принимает и отдает JSON. Навык — текстовая инструкция, как действовать. Упрощенно: сервер отвечает на вопрос «что агент может сделать», навык — «как это сделать».

Хост, клиент и сервер: как устроена схема

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

Сервер — отдельная программа, локальная или удаленная. Хост не передает ему всю переписку с моделью и ответы других серверов: сервер получает запрос и работает с теми данными, которые доступны ему по выданным правам. Сообщения — JSON-RPC 2.0 в кодировке UTF-8.

Сервер может предоставить три вида возможностей (примитивы):

Примитив Что это и пример Кто решает, когда использовать
tools (инструменты) функции, вызываемые по запросу модели: read_text_file, scan_secrets модель
resources (ресурсы) данные и контекст: файл проекта по адресу file:// обычно приложение: оно решает, как добавить ресурс в контекст, и может дать выбор пользователю
prompts (шаблоны) шаблоны сообщений и сценариев: «проверь изменения на секреты перед коммитом» пользователь

Локальные и удаленные серверы

Как клиент связывается с сервером, определяет транспорт. Стандартных транспортов два:

Транспорт Как работает и где сервер Когда рассматривать
stdio клиент запускает сервер дочерним процессом на той же машине, обмен — через стандартные потоки (stdin, stdout) локальные инструменты: файлы проекта, сканер секретов
Streamable HTTP сервер работает отдельно, локально или в сети; клиент шлет каждый запрос POST на один адрес общие сервисы: трекер, вики

Для новых подключений рекомендуют Streamable HTTP; старый транспорт HTTP+SSE устарел, но еще встречается.

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

Другой вариант — токен, заранее выданный сервисом, его прописывают в конфигурации вручную. Такой токен не обязательно ограничен одним MCP-сервером: его область задает сервис. Проверьте ее и выдайте только нужное право, например создавать задачи. В обоих случаях токен передают в заголовке каждого запроса, а не в адресе.

Если клиент поддерживает только stdio, к удаленному серверу его подключают через локальный пакет-прокси: он пересылает запросы, а порядок входа смотрите в его документации.

Что происходит при запуске IDE и при запросе пользователя

Порядок ниже описан по действующей на момент публикации редакции спецификации — 2026-07-28. Какая редакция действует сейчас, видно на странице версий MCP.

Отдельного рукопожатия при запуске в этой редакции нет: версия протокола и возможности клиента передаются в каждом запросе. До редакции 2025-11-25 включительно клиент сначала отправлял запрос initialize и согласовывал версию с сервером, такие серверы еще встречаются.

Путь от запуска IDE до ответа покажем на учебной схеме со сканером и трекером:

  1. Хост читает файл конфигурации, запускает локальные серверы (сканер) и подключается к удаленным (трекер).
  2. Клиент запрашивает список инструментов (tools/list) с названиями, описаниями и схемой параметров; в интерфейсе IDE сервер отмечается как активный.
  3. Пользователь пишет запрос: проверить src/settings.py на секреты и завести задачу, если что-то найдется.
  4. Агент отправляет модели системный промпт, историю, запрос и описания доступных инструментов.
  5. Модель отвечает не текстом, а просьбой вызвать инструмент: JSON с именем scan_secrets и аргументом path.
  6. Клиент отправляет серверу сканера tools/call, сервер выполняет проверку и возвращает результат: в строке 12 похоже на ключ доступа.
  7. Результат уходит модели, и она просит второй вызов — create_issue на сервере трекера. Клиент трекера отправляет его своему серверу, тот создает задачу и возвращает ее номер.
  8. Модель получает номер задачи и готовит ответ: что найдено, какая задача заведена и что ключ стоит отозвать.

Шаги 4-8 могут повторяться много раз. От зацикливания на одном вызове помогает лимит шагов, подробнее — в статье про агентный цикл.

Как выглядит обмен на деле, покажем на настоящем файловом сервере из следующего раздела. Его ответ на tools/list (фрагмент: описания сокращены, остальные инструменты и служебные поля опущены):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "read_text_file",
        "description": "Read the complete contents of a file from the file system as text.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "The file to read as text."
            }
          },
          "required": ["path"]
        },
        "annotations": {
          "readOnlyHint": true
        }
      }
    ]
  }
}

Вызов чтения файла. Версия протокола и возможности клиента передаются в _meta самого запроса:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "read_text_file",
    "arguments": {
      "path": "src/settings.py"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Ответ сервера (служебные поля _meta и structuredContent опущены):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [
      {
        "type": "text",
        "text": "DEBUG = False\nAPI_KEY = \"sk-test-not-a-real-key\"\n"
      }
    ]
  }
}

Поле resultType появилось в редакции 2026-07-28 и обязательно в ответах сервера, в том числе в tools/list. У серверов более старых редакций его нет, и клиент тогда считает результат завершенным.

Эти сообщения формирует и читает клиент: модель видит описание инструмента и результат, а не сам обмен. Сервер не обязан содержать ИИ — это обычная программа.

Если хотите научиться собирать агентов с инструментами на практике, записывайтесь на курс «Разработка ИИ-агентов».

Конфигурация: как подключить MCP-сервер к агенту

У каждого клиента свой файл конфигурации и формат (.mcp.json, у Codex — config.toml), путь к файлу и ключи сверяют с документацией своего клиента. Содержание при этом одно: имя сервера, команда запуска или адрес, переменные окружения. Строку подключения конкретного сервера обычно описывает его вендор.

Пример ниже — формат одного клиента, Claude Code: файл .mcp.json в корне проекта. Подключаем эталонный сервер файловой системы из официального репозитория эталонных серверов MCP. Он запускается локально через stdio и получает доступ только к указанной папке.

Флаг --read-only оставляет только инструменты чтения и списка папок: инструменты записи сервер не выдает вовсе. Версия пакета закреплена, чтобы пример не сломался после обновления:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2.4.0", "--read-only", "--confine-roots", "/home/user/projects/demo"]
    }
  }
}

Для версии 2.4.0 нужен Node.js 24 или новее. Флаг --confine-roots нужен для клиентов на старой редакции протокола: без него такой клиент может заменить список разрешенных папок своим. В новой редакции папки берутся только из командной строки.

После подключения проверьте результат по факту, а не по значку в интерфейсе:

  1. В списке инструментов сервера есть чтение файла и списка папки (read_text_file, list_directory), но нет записи (write_file, edit_file).
  2. На просьбу показать содержимое src/settings.py агент вызывает read_text_file и получает текст файла.
  3. Файл вне разрешенной папки сервер прочитать отказывается: в ответе ошибка «Access denied — path outside allowed directories».

Покажет ли клиент окно подтверждения перед вызовом, зависит от его настроек и режима: отсутствие окна само по себе не означает ошибку подключения. Если хотите подтверждать вызовы вручную, в Claude Code это настраивается для отдельного инструмента.

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

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TRACKER_TOKEN}"
      }
    }
  }
}

Если удаленный сервер использует OAuth, токен вручную в .mcp.json прописывать не нужно: его получает и хранит клиент, а в заголовке Authorization отправляет сам. В Claude Code для такого входа может понадобиться отдельная команда, поэтому порядок входа смотрят в документации клиента.

Ручной токен не пишут в проектный файл открытым текстом: такой файл часто попадает в репозиторий. Его держат в защищенном хранилище или подставляют из переменной окружения, как ${TRACKER_TOKEN} в примере. Токен, который оказался в файле или на экране, отзывают и выпускают новый.

Общие и проектные серверы

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

У Claude Code общие серверы лежат в ~/.claude.json, а проектные — в .mcp.json, который можно хранить в git. Так сервер попадает к коллегам вместе с кодом.

Поэтому в интерактивной сессии Claude Code просит подтвердить серверы из проектного файла перед первым использованием. В некоторых неинтерактивных режимах проектный сервер загружается без этого диалога — учитывайте это, если запускаете агента в скриптах.

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

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

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

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

Риск Откуда берется Что сделать
Чужой код на машине локальный сервер работает с правами клиента, вредной может быть команда запуска или код пакета смотреть команду до подключения, закреплять версию пакета, запускать в контейнере с доступом только к нужным папкам и сети
Данные уходят удаленному серверу что отправить, решает модель, и на просьбу сервера она может передать лишнее, например переменные окружения подключать только доверенные серверы; не передавать токены в окружение недоверенного локального сервера; для удаленного доступа — вход через OAuth клиента или токен только нужному процессу
Промпт-инъекция через данные внешний контент (страницы, задачи, письма) может нести инструкции для модели проверять сервер до подключения, подтверждать действия, не давать лишних прав
Опасные инструменты удаление, запись, очистка отключить ненужные в настройках сервера (у файлового сервера — режим только чтения); запись на старте — только в тестовой среде, в рабочей — минимальные права и подтверждение опасных действий
Широкие права токена при утечке такой токен открывает все сразу минимальные права на старте, расширять по мере надобности
Токены в конфиге и на экране секрет в файле открытым текстом или показан на демонстрации ручной токен — из защищенного хранилища или окружения, при OAuth токеном управляет клиент; показанный — отозвать
Локальный HTTP-сервер доступен другим программам сервер слушает все интерфейсы и не проверяет источник запроса слушать только 127.0.0.1, проверять заголовок Origin, требовать аутентификацию

Контейнер дает локальному серверу песочницу, но от удаленного сервера не защищает. Локальный пакет-прокси — тоже точка доверия: если его взломают, пострадают все его пользователи.

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

Подтверждение снижает риск, но не гарантирует защиту: если подтверждать все подряд, оно перестает работать. Надежнее, когда опасного инструмента и секретов в окружении у агента нет. Угрозы удобно вести таблицей «сценарий — слой защиты — тест — владелец», чтобы каждая попала в бэклог.

Пример из 1С: MCP-инфраструктура разработчика

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

  • поиск и выполнение кода в базе: сервер читает метаданные или код модуля и возвращает только ответ;
  • справка по синтаксису для нужной версии платформы;
  • связь с ассистентом 1С:Напарник;
  • работа со средой разработки 1С:EDT;
  • тестирование.

Как это выглядит в задаче. Разработчик просит агента найти, где в конфигурации считается скидка, и проверить расчет на тестовом заказе.

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

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

Адреса серверов прописывают в конфигурации агента, а в файле правил для агента (AGENTS.md и аналоги) — как с ними работать.

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

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

Даже инструмент запуска тестов можно подключить как MCP-сервер или вызывать из командной строки. Разница не в формате ответа: MCP-инструмент может вернуть и текст, и структурированные данные, а команда тоже может выдать JSON. Локальную команду проще запустить и поменять.

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

Если не работает

Типовые сбои и что с ними делать:

Симптом Вероятная причина Что сделать
Сервер не стартует ошибка в команде или пути, нет среды выполнения или она старая (для файлового сервера 2.4.0 нужен Node.js 24) запустить команду из конфигурации вручную, поправить путь, установить или обновить среду
Два сервера мешают друг другу у серверов с сетевым транспортом (HTTP) один и тот же порт; локальные серверы на stdio порт для обмена с клиентом не занимают развести порты или убрать дублирующий сервер
Агент путает инструменты или берет не тот подключено слишком много похожих инструментов отключить лишние серверы и инструменты
Ближе к концу длинной сессии модель путает или повторяет вызовы контекст близок к пределу модели сжать сессию или начать новую
Вызов завершается ошибкой подключения тайм-аут, разрыв соединения, ошибка сервера посмотреть сообщение клиента и журнал сервера
Удаленный сервер отказывает в доступе токен истек или не выдан пройти вход заново
Агент повторяет один и тот же вызов петля в агентном цикле ограничить число шагов агента

FAQ

MCP работает только с Claude?
Нет. Это открытый протокол, который Anthropic представила в ноябре 2024 года, и его поддерживают многие клиенты. С декабря 2025 года MCP развивается в Agentic AI Foundation — фонде под эгидой Linux Foundation.

Можно ли подключить MCP-серверы к локальной модели?
Протоколу модель не важна, но она должна уметь вызывать инструменты. Насколько надежно она это делает, проверьте на своем сценарии.

Как написать свой MCP-сервер?
Для этого есть официальные SDK для нескольких языков. Эталонные серверы из репозитория modelcontextprotocol/servers — учебные реализации, а не готовые решения для продакшена. Разработка своего сервера — отдельная тема.

Что изучить дальше

Подключение инструментов — одна из частей разработки агента, наряду с агентным циклом, памятью и проверкой поведения. Если хотите собрать агента с инструментами от постановки задачи до проверки, записывайтесь на курс «Разработка ИИ-агентов».

Чтобы задать вопросы практикующим разработчикам, посмотрите расписание и выберите подходящую тему среди открытых уроков Otus.

Смежные темы: Как создать ИИ-агента, RAG в LLM.

Выводы

Коротко о главном:

  • MCP — протокол между приложением и сервером, а не замена вызову функций: модель просит вызвать инструмент, приложение исполняет вызов через сервер.
  • У каждого сервера свой клиент внутри хоста. Сервер получает запрос, а не всю переписку, и работает с данными, доступными ему по выданным правам.
  • Локальный сервер запускают через stdio, удаленный подключают по HTTP; вход — через OAuth клиента или ручной токен с минимальной областью.
  • Подключение проверяют по факту: нужные инструменты есть в списке, лишних нет, разрешенный файл читается, файл вне папки — нет.
  • MCP нужен, когда один набор инструментов нужен нескольким клиентам или всей команде; для одного приложения хватит вызова функций или командной строки.
  • Что сделать у себя: начните с файлового сервера в режиме только чтения, закрепите версию пакета, проверьте три признака из раздела о конфигурации, а запись и опасные инструменты включайте только в тестовой среде.
OTUS Журнал
1+0=2 (поп-ап)