Представьте: вы подключили к Claude Desktop или к своему агенту MCP-сервер, агент его «видит», инструменты в списке есть — а на первом же реальном запросе он выбирает не тот инструмент, отправляет в него мусорные аргументы и молча получает ошибку. Внешне всё работает. По факту — нет.
Это типичная точка, где новичок в MCP застревает. Не на «как написать сервер» — это как раз быстро. А на дизайне инструментов, на транспортах и на том, что происходит, когда рядом с вашим сервером живут ещё пять чужих.
MCP (Model Context Protocol) — открытый протокол, который описывает, как AI-приложение (клиент) общается с внешними источниками контекста и действий (серверами). Сервер объявляет инструменты (tools), ресурсы (resources) и промпты (prompts), клиент их читает и передаёт модели. Разобраться в теме стоит потому, что именно здесь решается, будет ли агент полезен в реальной работе или останется демо.
Что на самом деле даёт MCP и где проходит граница
Ключевая идея проста: вместо того чтобы вшивать в промпт «как сходить в базу», вы описываете действие как инструмент с именем, описанием и схемой аргументов. Модель сама решает, когда его вызвать. Это снимает с промпта огромный кусок логики и делает поведение предсказуемее — но только если описание инструмента написано для модели, а не для человека.
И вот первая неочевидная вещь. Описание инструмента — это не документация, это промпт. Модель видит имя, description и JSON-схему аргументов и по ним выбирает. Чем больше в вашем сервере инструментов с похожими названиями (get_user, fetch_user, find_user), тем выше шанс, что агент выберет не тот. Практик ограничивает набор и делает описания взаимоисключающими.
Разбор одной задачи: сервер для работы с заявками
Возьмём конкретное: есть внутренняя система заявок, и вы хотите, чтобы агент мог найти заявку по номеру, посмотреть её статус и перевести в другой статус. Разберём, как это делает практик, и где всё ломается.
Шаг 1. Разделить чтение и запись. Инструменты чтения (get_ticket, list_tickets) безопасны и вызываются свободно. Инструмент записи (update_ticket_status) — потенциально разрушителен: агент может перевести заявку в «закрыта» по ошибке. Практик либо не даёт агенту право записи вообще, либо требует явного подтверждения и ограничивает допустимые переходы в самой схеме аргументов (перечисление статусов, а не свободная строка).
Шаг 2. Сделать аргументы строгими. Если ticket_id — строка без формата, модель пришлёт «заявка 1234» или «#1234». Если это integer с описанием «числовой идентификатор без решётки», ошибок на порядок меньше. Схема аргументов — ваш главный инструмент защиты от мусора на входе.
Шаг 3. Продумать ответ. Инструмент возвращает не всю запись из базы, а компактный результат: номер, статус, дату, исполнителя. Если вернуть 40 полей, вы съедите контекст модели и повысите шанс, что на следующем шаге она запутается. Ответ инструмента — тоже часть дизайна.
Шаг 4. Ошибки — как данные, а не как падение. Если заявки нет, инструмент должен вернуть понятный результат «не найдено», а не выбросить исключение, которое клиент покажет как сбой сервера. Модель умеет обрабатывать «не найдено»; на «internal error» она часто начинает повторять вызов.
Что пойдёт не так, если сделать иначе. Классический сценарий: разработчик отдаёт один универсальный инструмент manage_ticket(action, params) со свободной строкой параметров. Модель заполняет params как получится, сервер парсит и падает на половине вызовов. Второй сценарий: инструмент записи без ограничения переходов — агент «закрывает» заявки, которые закрывать было нельзя, и заметить это получается только по логам постфактум.
Транспорты: почему выбор stdio или SSE — не формальность
MCP поддерживает несколько транспортов, и выбор между ними определяет, где сервер вообще можно запустить.
- stdio — сервер запускается как дочерний процесс клиента, общение через стандартный ввод-вывод. Просто, локально, без сети. Минус: один клиент — один процесс, горизонтально не масштабируется, а логи легко перемешать с протокольным потоком.
- SSE / HTTP — сервер живёт отдельно и доступен по сети. Нужен, когда сервер общий для команды или нескольких клиентов. Плата — аутентификация, сетевые таймауты, вопросы доступа.
Практическое правило: начинайте со stdio, переходите на сетевой транспорт, когда сервер должен обслуживать больше одного клиента. Многие проекты страдают от обратного — сразу поднимают сетевой сервер, а потом тратят время на аутентификацию, которая для локального сценария не нужна вовсе.
Где ломается сама схема MCP
Это не ошибки читателя — это режимы отказа самой архитектуры. Их полезно знать заранее.
1. Инструмент перестал работать на стороне источника. Внешний API сменил формат ответа или ввёл лимит запросов. Ваш сервер формально жив, но возвращает мусор. Заметить заранее: держать проверку ответа источника и возвращать явную ошибку «источник недоступен», а не пустой результат. Если уже поздно — по логам вызовов видно, что доля ошибок выросла на конкретном инструменте.
2. Модель выбирает инструмент не по назначению. С ростом числа инструментов (свои + чужие серверы) растёт неопределённость выбора. Заметить заранее: следить, какие инструменты агент вызывает на типовых запросах. Если уже поздно — сокращать набор, переименовывать конфликтующие инструменты, добавлять в описания явные границы применения.
3. Изменился контекст клиента. Клиент обновился, поменял способ отображения инструментов или лимит на их количество. Сервер работает, а инструменты просто не появляются. Заметить заранее: фиксировать версию клиента в тестах. Если уже поздно — проверять подключение минимальным сервером с одним инструментом.
4. Схема аргументов оказалась слишком свободной. Сначала всё хорошо, потом модель начинает присылать аргументы, которые формально проходят, но семантически неверны. Заметить заранее: валидировать не только тип, но и диапазон/формат. Если уже поздно — сужать схему и добавлять перечисления вместо свободных строк.
Пути освоения и их честная цена
Есть три реальных маршрута, и они отличаются не только временем.
| Путь | Время | Деньги | Что получаете |
|---|---|---|---|
| Самостоятельно по докам и примерам | недели, рвано | бесплатно | рабочий сервер, но дыры в дизайне инструментов и транспортах |
| Свой pet-проект + чтение чужого кода | 1–2 месяца | бесплатно | лучше всего закрепляет, но нет обратной связи по решениям |
| Структурированный курс | компактнее | стоимость курса | порядок тем и разбор типичных ошибок |
Самостоятельный путь честно работает, если у вас уже есть опыт с API и вы умеете читать спецификации. Главный барьер — не с кем сверить решение: вы сделали инструмент, он вроде отвечает, а правильно ли он спроектирован для модели — непонятно. Ошибки дизайна проявляются позже и дороже, чем ошибки синтаксиса.
Курс закрывает именно этот барьер: там разбирают дизайн инструментов и ресурсов, транспорты и то, как довести сервер до production с мониторингом — то есть ровно те места, где самостоятельное освоение буксует. Если тема пересекается с защитой агентов, полезно параллельно посмотреть материал про AI-безопасность и guardrails, а за контекстом внедрения — AI-автоматизация бизнеса.
Кому этот путь подходит, а кому нет
Подходит, если вы разработчик с опытом работы с API и JSON, хотите дать своим агентам реальные действия, а не только текст, и готовы думать про дизайн инструментов, а не только про код. Подходит и тем, кто строит внутренние интеграции и хочет стандартный способ подключать источники к разным клиентам.
Не подходит, если вы ждёте «магию»: MCP не решает за вас, какие действия давать модели и как ограничить риск. Не подходит, если нет базового опыта с HTTP и схемами данных — сначала стоит закрыть это. И не стоит идти сюда ради быстрого результата без готовности разбираться в транспортах и отказах.
MCP — это про то, чтобы создаём MCP-серверы и инструменты, которые расширяют возможности любых AI-агентов и интеграций, осознанно, а не наугад. Если хотите пройти этот путь с разбором типичных ошибок и обратной связью по вашим решениям — посмотрите MCP-серверы и инструменты для AI: там тема разобрана от протокола до production-сервера с мониторингом.