MCP или Skills в Claude Code: где хранить инструкцию для повторяемой задачи в 2026

Что такое MCP и зачем он нужен в Claude Code?

Когда Claude работает только с файлами в папке, он не видит автоматически данные из других систем. Ошибки могут лежать в Sentry, задачи - в Linear, документация - в базе знаний, а исходники - локально. MCP создаёт для Claude Code путь к этим внешним источникам.

Anthropic описывает MCP как стандарт подключения ИИ-помощников к системам, где живут данные:

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

Представь задачу: «Проверь последние ошибки и создай тикет». Для неё нужны две вещи:

• доступ к ошибкам;
• доступ к тикет-трекеру.

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

MCP не хранит инструкцию. Он не заменяет SKILL.md, промпт или CLAUDE.md. Его задача уже: доставить Claude внешние ресурсы и действия.

Что такое MCP-сервер простыми словами?

Если MCP представить как правила разговора, MCP-сервер - это собеседник, который знает конкретную систему. Один сервер может дать доступ к базе знаний. Другой - к Linear. Третий - к Sentry или другому dev-инструменту.

Связка выглядит так:

Claude Code -> MCP-сервер -> внешний сервис

Claude Code здесь выступает клиентом. Он отправляет запрос через MCP-сервер. Сервер обращается к внешнему сервису и возвращает доступный результат или выполняет действие.

Документация Model Context Protocol разводит эти понятия прямо:

Поэтому фраза «подключить MCP» может означать разные действия. Иногда речь идёт о протоколе как о способе соединения. На практике в Claude Code подключается конкретный MCP-сервер.

Это похоже на разницу между «подключить интернет» и «открыть конкретный сайт». Протокол задаёт способ обмена. Сервер даёт конкретное содержимое и функции.

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

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

Как Claude работает с MCP и внешними инструментами?

Есть два базовых сценария.

Чтение внешних ресурсов. Claude получает данные, которых нет среди локальных файлов. Например, подтягивает ошибки из Sentry, ищет описание задачи в Linear или читает страницу базы знаний.

Действие во внешнем сервисе. Claude вызывает предоставленный инструмент. Например, создаёт задачу, отправляет данные или выполняет другую операцию, которую разрешил MCP-сервер.

Anthropic описывает это так:

Разница между чтением и действием важна из-за риска. Прочитать список ошибок - одно. Создать тикет, изменить запись или запустить операцию - другое. MCP даёт техническую возможность, но не решает, когда действие допустимо.

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

MCP может подключаться к:

• Sentry и другим dev-инструментам;
• Linear и системам управления проектами;
• базам знаний;
• внешним API;
• файловым и другим системам, которые предоставляет конкретный сервер.

Я не жду от MCP готового рабочего процесса. Он открывает дверь. Что делать после входа, описывает Skill.

Чем MCP отличается от Skills?

Anthropic формулирует границу одной строкой:

Образ, который помогает не путаться: MCP - это кухня, Skill - рецепт.

Кухня даёт продукты, ножи и плиту. Рецепт говорит, что взять, в каком порядке смешать, сколько проверять и что поставить на стол. Если есть только кухня, Claude может получить доступ к данным, но не знать твой рабочий порядок. Если есть только рецепт, но нет кухни и продуктов, ему нечего читать и нечем действовать.

Например, MCP подключает базу. Skill описывает схему таблиц, нужные query patterns и порядок проверки результата. MCP подключает deployment-сервис. Skill говорит, какие тесты запустить, когда просить подтверждение и как отчитаться.

Есть ещё CLAUDE.md. Он нужен для постоянных правил проекта, которые должны применяться на каждой сессии. Skill подходит для инструкции, которая включается по ситуации. MCP нужен для внешнего соединения.

Anthropic разводит роли расширений так:

Я бы держал это правило перед глазами: MCP даёт доступ, Skill задаёт способ работы, CLAUDE.md хранит постоянные правила.

Если инструкция требует опасного действия, автоматический запуск Skill лучше отключить через disable-model-invocation: true. Тогда запуск остаётся ручным.

Где хранить инструкцию для конкретной задачи?

Skill состоит из каталога и обязательного файла SKILL.md. Внутри файла две части:

• YAML frontmatter с метаданными;
• Markdown с инструкцией, по которой Claude выполняет задачу.

Минимальная структура:

.claude/
└── skills/
    └── deploy/
        └── SKILL.md

В Skill можно хранить:

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

Пример процедуры для публикации:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

CLAUDE.md нужен не для разовой процедуры. Если правило звучит как «всегда запускай тесты перед изменением файлов» или «в каждом ответе показывай изменённые файлы», оно относится к постоянному контексту проекта.

Разница на практике:

• «Всегда используй такой формат именования» - CLAUDE.md.
• «Когда готовишь релиз, выполни семь шагов и составь отчёт» - Skill.
• «Получи данные из deployment-сервиса» - MCP.
• «Получи данные из deployment-сервиса, выполни проверки и дождись подтверждения» - MCP + Skill.

Не складывай всю документацию в один файл. Если правило нужно всегда, оно должно быть коротким и заметным. Если процедура нужна иногда, вынеси её в Skill. Так Claude проще отличить постоянный фон от задачи по ситуации.

Нужен ли MCP для твоей задачи?

Применяй простое правило:

1. Нужен внешний сервис, данные или действие - MCP.
2. Нужна инструкция или workflow - Skill.
3. Нужны внешний доступ и порядок действий - MCP + Skill.
4. Правило должно работать в каждой сессии - CLAUDE.md.

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

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

Примеры:

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

Как подключить MCP к Claude Code?

1. Выбери подходящий MCP-сервер.

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

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

2. Открой терминал в проекте.

   Перейди в корень проекта, где Claude Code должен видеть подключение.

   Для project scope это важно: конфигурация проекта хранится рядом с исходниками, вместо случайной папки. Если команда запускается вне нужного проекта, потом легко решить, что сервер не подключился.

3. Добавь локальный сервер.

   Выполни команду claude mcp add с транспортом stdio.

   bash

   Скопировать

   claude mcp add --transport stdio my-server -- command-to-start-server

   Здесь my-server - имя подключения, а command-to-start-server - команда запуска конкретного MCP-сервера.

4. Передай переменные окружения.

   API-ключи и другие переменные добавляй через --env.

   bash

   Скопировать

   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

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

5. Отдели параметры Claude Code.

   Поставь -- перед командой и аргументами MCP-сервера.

   До разделителя идут параметры Claude Code:

   • --transport;
   • --env;
   • --scope.

   После разделителя идут команда запуска сервера и её аргументы:

   bash

   Скопировать

   claude mcp add \
     --transport stdio \
     --scope project \
     my-server \
     -- python server.py --port 8080

   Официальная документация объясняет назначение разделителя:

   «Двойной дефис -- отделяет параметры Claude Code, такие как --transport, --env и --scope, от команды и аргументов, которые запускают сервер».

   • Claude Code Docs, Connect Claude Code to tools via MCP

6. Запусти Claude Code из корня.

   Открой Claude Code в той же папке проекта, где находится project-конфигурация.

   Так Claude Code сможет увидеть проектный сервер и связанный с ним .mcp.json, если конфигурация создаётся в project scope.

7. Проверь подключение.

   Внутри Claude Code выполни команду:

   Скопировать

   /mcp

   Панель /mcp показывает подключённые серверы и количество инструментов рядом с каждым из них. Если сервер не отображается, не делай вывод только по одному списку. Дополнительно проверь имя и scope.

   bash

   Скопировать

   claude mcp get my-server

8. Отдельно проверь действие.

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

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

Где настраивается MCP в Claude Code?

Минимальный проектный файл:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Файл должен называться именно .mcp.json и лежать в корне проекта. Не клади его в домашнюю папку только потому, что это конфигурационный файл. .mcp.json не является пользовательским глобальным файлом.

Документация связывает project scope с командной работой:

Разница scope:

• project - подключение для конкретного проекта;
• user - личная настройка;
• local - локальная настройка для текущей рабочей среды.

Личная конфигурация хранится в ~/.claude.json. Проектная - в .mcp.json. Подробнее о первом подключении - в отдельном разборе. Выбирай scope по тому, кому нужен сервер.

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

Как создать Skill и положить его в проект?

Структура проектного Skill:

.claude/
└── skills/
    └── review-release/
        └── SKILL.md

Файл SKILL.md с минимальным содержимым:

---
name: review-release
description: Use when checking a release before deployment, including tests, build results, changed files, and deployment readiness.
---

1. Check the changed files.
2. Run the test suite.
3. Build the application.
4. Report failures and open questions.
5. Do not deploy without confirmation.

Frontmatter находится между двумя строками ---. В нём задаются метаданные Skill. Главное поле для автоматического выбора - description.

Пиши описание с условием запуска. Сравни:

description: Rules for releases

и:

description: Use when checking a release before deployment, including tests, build results, changed files, and deployment readiness.

Второй вариант даёт Claude больше признаков для сопоставления с задачей. Но описание не превращает автоматический запуск в жёсткое правило.

Прямой запуск:

/review-release

Личный Skill хранится в:

~/.claude/skills/<skill-name>/SKILL.md

Такой Skill доступен во всех проектах. Проектный Skill лежит здесь:

.claude/skills/<skill-name>/SKILL.md

Он относится к текущему проекту.

Если Skill выполняет опасные действия, добавь:

disable-model-invocation: true

Тогда запуск останется ручным. Это полезно для публикации, деплоя, удаления и других операций с побочным эффектом.

Как использовать MCP и Skill вместе?

Представь рабочий процесс:

1. MCP подключает базу.
2. Skill объясняет схему данных.
3. Skill задаёт query patterns.
4. Claude получает только нужные записи.
5. Skill описывает проверку результата.
6. Claude отдаёт отчёт в заданном формате.

Минимальный .mcp.json:

{
  "mcpServers": {
    "my-service": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Минимальный SKILL.md:

---
name: use-my-service
description: Use the connected service when the task requires checking project data or creating an item there.
disable-model-invocation: true
---

Use the connected MCP service.

1. Confirm what data or action is needed.
2. Query only the relevant resource.
3. Explain the result briefly.
4. Ask for confirmation before any destructive action.

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

Тот же принцип работает для deployment-сервиса:

• MCP даёт доступ к сервису;
• Skill требует запустить тесты;
• Skill требует проверить сборку;
• Skill задаёт порядок публикации;
• Skill требует подтвердить результат.

И для тикет-трекера:

• MCP даёт чтение и создание тикетов;
• Skill описывает обязательные поля;
• Skill задаёт формат заголовка;
• Skill требует сначала показать черновик;
• Skill запрещает создавать дубликат.

Anthropic приводит именно такую связку:

Не проси Skill заменить MCP. Инструкция может описать действие, но без подключённого сервиса Claude не получит внешний ресурс. И не проси MCP заменить Skill: соединение само по себе не задаёт рабочий процесс.

Что делать, если MCP не подключается?

Проверь ошибки по порядку.

1. Проверь корень проекта. Убедись, что .mcp.json лежит в корневой папке проекта, а Claude Code запущен из неё.

   bash

   Скопировать

   pwd
   ls -la .mcp.json

   .mcp.json не является глобальным пользовательским файлом. Если он лежит в домашней папке, Claude Code не обязан использовать его как проектную конфигурацию.

2. Проверь правильный список. Project-сервер может не появиться в выводе claude mcp list, хотя он работает в сессии.

   bash

   Скопировать

   claude mcp get <server-name>

   Затем запусти Claude Code в корне проекта и выполни:

   Скопировать

   /mcp

   В описанной проблеме project-сервер не показывался в claude mcp list, но был доступен во время сессии. Поэтому отсутствие в одном списке не доказывает отсутствие подключения.

3. Проверь разделитель --. Убедись, что параметры Claude Code закончились до команды запуска сервера.

   Правильная форма:

   bash

   Скопировать

   claude mcp add \
     --transport stdio \
     --scope project \
     my-server \
     -- python server.py --port 8080

   До -- находятся --transport, --scope и другие параметры Claude Code. После -- идут python server.py и --port 8080.

4. Проверь переменную окружения. Если сервер ждёт ключ или другую переменную, передай её через --env.

   bash

   Скопировать

   claude mcp add \
     --env SERVICE_API_KEY=key-value \
     --transport stdio \
     my-server \
     -- command-to-start-server

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

5. Проверь JSON. Если конфигурация хранится в .mcp.json, проверь структуру и список серверов.

   bash

   Скопировать

   jq empty .mcp.json
   jq -r '.mcpServers | keys[]' .mcp.json

   Первый вызов проверяет корректность JSON. Второй выводит имена внутри mcpServers.

6. Запусти диагностику Claude Code. Выполни:

   Скопировать

   /doctor

   Команда помогает отделить проблему конфигурации от проблемы конкретного сервера. После исправления снова проверь /mcp.

Почему Claude не запускает Skill автоматически?

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

• что делает Skill;
• когда его надо применять.

Слабый вариант:

description: Rules for components

Сильнее:

---
name: component-development
description: Use when creating or modifying Angular component files such as .component.ts, .component.html, or .component.scss, including adding @Input or @Output decorators.
---

Во втором описании есть условие запуска, типы файлов и конкретные действия. Это не гарантия, но Claude получает больше признаков для сопоставления.

Документация прямо указывает роль поля:

Есть две разные проверки.

Skill установлен и найден. Проверь прямой вызов:

/explain-code

Если прямой запуск не работает, сначала исправляй структуру каталога, имя файла или содержимое frontmatter.

Модель сама выбрала Skill. После успешного прямого запуска отправь обычный запрос, который подходит под description. Если Skill не включился, это ещё не доказывает поломку установки. Модель могла не сопоставить задачу с описанием.

Формального алгоритма выбора нет. Документация не задаёт порог совпадения, приоритеты Skills и порядок разрешения пересекающихся описаний. Гарантированного механизма, который заставляет модель применять Skill во всех подходящих случаях, тоже нет.

Практическая схема проверки:

1. Запусти Skill вручную.
2. Убедись, что инструкция выполняется.
3. Сделай description конкретнее.
4. Проверь автоматический запуск на ясном запросе.
5. Для опасных действий оставь ручной запуск.

Сколько MCP-серверов и Skills стоит подключать?

Проблема не только в количестве серверов. Каждый MCP может добавлять описания инструментов и промежуточные результаты. Claude приходится учитывать их вместе с задачей и файлами проекта.

Anthropic описывает масштаб, до которого легко дойти:

А затем предупреждает о последствиях:

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

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

В статье Anthropic приведён измеримый пример:

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

Anthropic предлагает проверить конфигурацию после примерно 20-50 одновременно включённых Skills. Это не жёсткий лимит и не обещание, что на 19 всё будет работать идеально. Это сигнал остановиться и проверить:

• не пересекаются ли description;
• не дублируют ли Skills друг друга;
• не слишком ли длинные инструкции;
• нельзя ли убрать ненужный Skill;
• не пора ли вынести подробности в отдельные файлы.

Главное правило: подключай нужный минимум. MCP оставляет доступ к внешним возможностям. Skill описывает процесс. Лишнее в обеих местах увеличивает шум.

Вопросы и ответы