MCP-сервер что это: 7 шагов до первого инструмента в Claude Code

Я собрал эту инструкцию, чтобы ты подключил первый сервер за 10 минут и увидел результат, а не разбирался в документации неделю. https://vibeceh.ru/?utm_source=article&utm_campaign=mcp-podklyuchit-pervyj-instrument&utm_content=cta-top#buy

MCP-сервер: что это простыми словами

Представь USB-C для ИИ. Один разъём подходит для разных устройств. Здесь вместо устройства подключается внешний сервис.

Я подключаю MCP-сервер, и Claude Code остаётся той же моделью. Агент не обучается навсегда. Сервер решает более узкую практическую задачу:

• агент получает доступ к данным за пределами чата;
• видит доступные действия;
• принимает запрос агента;
• возвращает результат из внешней системы.

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

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

Как MCP-сервер связывает Claude Code с внешним инструментом

Запрос «mcp сервер как работает» сводится к простой цепочке:

1. Claude Code запускается как MCP-клиент.
2. MCP-сервер сообщает, какие инструменты доступны.
3. Claude Code получает описания этих инструментов и их схемы.
4. Агент выбирает действие в рамках задачи.
5. MCP-сервер обращается к внешней системе.
6. Результат возвращается в Claude Code.

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

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

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

Зачем нужен MCP-сервер в обычной работе

Запрос «зачем нужен mcp сервер» лучше проверять по своей рутине и конкретной функции. Вспомни действие, которое повторяется:

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

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

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

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

Практикум по вайб-кодингу связан с той же задачей: собрать рабочую связку руками и проверить, что она делает. Там этот подход проходит на практических сценариях.
https://vibeceh.ru/?utm_source=article&utm_campaign=mcp-podklyuchit-pervyj-instrument&utm_content=cta-mid#buy

MCP, навык и обычный API: в чём разница

Skill отвечает на вопрос «как выполнять процедуру». Это может быть чек-лист, шаблон поведения или набор инструкций в файле SKILL.md.

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

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

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

Какие бывают MCP-серверы: примеры для первого знакомства

Запрос «примеры mcp серверов» можно разложить по типу работы:

• Playwright MCP управляет браузером. Через него Claude может открыть страницу и проверить её содержимое.
• Memory MCP 1file хранит локальную память. Данные остаются на машине.
• Filesystem MCP читает, записывает, ищет и перемещает файлы, а также показывает метаданные. Для первого опыта лучше ограничить его одним каталогом проекта.
• Context7 подставляет в контекст актуальную документацию библиотек и фреймворков.
• Fetch MCP загружает веб-страницы, API-ответы и документы и преобразует их в текст.

Есть и серверы для других систем. В источниках также упоминаются GitHub, Google Workspace и SQLite, но они не подходят для самого короткого первого сценария: там появляются токены, OAuth, права доступа или дополнительные ограничения.

Не выбирай сервер по громкому названию. Сначала задай вопрос: какое действие он убирает? Если ответа нет, подключение пока не нужно.

Как выбрать первый полезный MCP-сервер

Оценивай сервер по самому частому ручному переносу данных. Подойдут такие признаки:

1. Ты регулярно копируешь один и тот же тип информации из внешнего сервиса.
2. Источник нужен в рабочих задачах, а не только для эксперимента.
3. Результат можно проверить одним чтением или простым действием.
4. Для подключения не требуются широкие права и production-доступ.
5. У сервера понятный небольшой набор инструментов.

Хороший первый сценарий выглядит так: открыть страницу, найти нужный фрагмент, вернуть его в Claude Code. Или прочитать один каталог проекта и найти в нём файл.

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

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

Где найти бесплатный готовый MCP-сервер

Запрос «бесплатные mcp сервера» приводит к нескольким типам источников:

• GitHub-репозитории отдельных серверов;
• подборки вроде Awesome MCP Servers;
• списки бесплатных MCP-серверов;
• каталоги с группировкой по задачам.

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

Anthropic отдельно предупреждает о сторонних серверах. Удалённый сервер может изменить поведение после подключения. Локальный сервер позволяет прочитать код и закрепить версию, но проверка всё равно нужна.

Перед подключением проверь:

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

Публичный HTTP-адрес удобен для первого теста, но сам по себе не делает сервер безопасным для любых данных. Сначала проверь read-only сценарий.

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

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

В отчёте о нескольких AWS MCP-серверах зафиксирован статический расход 18,3 тыс. токенов, или 9,2% контекста. Там же указано, что такой расход уменьшал эффективное окно примерно на 4-5 тыс. строк кода.

Ещё одно ограничение: после изменения доступности MCP-сервера требовался перезапуск сессии. Добавление посреди длинного разговора может привести к потерям.

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

• один сервер;
• одна понятная зона работы;
• небольшой набор инструментов;
• один проверяемый сценарий.

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

Как подключить первый MCP-сервер к Claude Code

1. Открой терминал вне Claude Code.

   Команда регистрации выполняется в терминале, а не в активном диалоге claude.

2. Добавь официальный тестовый сервер.

   Это публичный HTTP-сервер документации Claude Code.

   bash

   Скопировать

   claude mcp add --transport http \
    claude-code-docs \
    https://code.claude.com/docs/mcp

   Здесь claude-code-docs - имя сервера. URL указывает на MCP-эндпоинт документации.

3. Проверь список подключений.

   Выполни команду в том же терминале.

   bash

   Скопировать

   claude mcp list

   В списке должен появиться сервер claude-code-docs. Сохранённая запись показывает, что настройка прошла, поэтому дополнительно смотри на статус.

4. Проверь статус соединения.

   Ищи такой сигнал:

   Скопировать

   claude-code-docs ... ✔ Connected

   Если видишь только сообщение о добавлении записи, этого недостаточно. Нужна проверка через claude mcp list.

5. Запусти Claude Code.

   bash

   Скопировать

   claude

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

6. Выполни проверочный запрос с именем сервера.

   Такой запрос исключает случайный ответ без вызова MCP.

   prompt

   Скопировать

   Use the claude-code-docs server to look up what MCP_TIMEOUT does.

   В ответе ищи объяснение MCP_TIMEOUT и вызов инструмента с именем claude-code-docs.

7. Открой список внутри сессии.

   Команда показывает подключённые серверы, их статус и доступные инструменты.

   Скопировать

   /mcp

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

Как понять, что Claude Code действительно видит инструмент

Проверяй два сигнала:

1. В терминале команда claude mcp list показывает ✔ Connected.
2. В выводе Claude появляется вызов инструмента с именем claude-code-docs.

Одна запись в списке ещё не подтверждает рабочее соединение. При наличии статуса и отсутствии вызова Claude мог ответить встроенными знаниями или использовать другой инструмент.

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

Где хранится подключение и почему сервер исчезает в другом проекте

Официальная документация описывает три области:

• local - запись в ~/.claude.json внутри текущего проекта. Доступ только текущему пользователю и только в этом проекте.
• project - файл .mcp.json в корне проекта. Настройка доступна тем, кто клонирует проект.
• user - верхнеуровневый ключ mcpServers в ~/.claude.json. Сервер доступен текущему пользователю во всех проектах.

По умолчанию используется local. Поэтому сервер может работать в одном каталоге и исчезать в другом.

Для общего проекта:

claude mcp add --scope project --transport http \
  claude-code-docs https://code.claude.com/docs/mcp

Для всех проектов текущего пользователя:

claude mcp add --scope user --transport http \
  claude-code-docs https://code.claude.com/docs/mcp

Не отправляй секреты в .mcp.json, если файл попадёт в Git. Уровень project удобен для общей конфигурации, но доступы и ключи требуют отдельной проверки.

Что делать, если MCP-сервер подключён, но не работает

Иди по порядку:

1. Проверь список в терминале.

   bash

   Скопировать

   claude mcp list

   Убедись, что сервер есть и у него нет статуса ошибки или ожидания.

2. Открой список внутри Claude Code.

   Скопировать

   /mcp

   Команда показывает серверы, статус и доступные tools.

3. Уточни обязательные переменные. Если список tools пуст, сервер может требовать API-ключ или другую переменную окружения.

   bash

   Скопировать

   claude mcp add --env KEY=value ...

4. Перезапусти Claude Code после изменения .mcp.json. Конфигурация читается при старте сессии. Изменение файла в уже открытом диалоге не гарантирует обновление подключения.

5. Проверь каталог запуска. Сервер уровня local должен относиться к тому же проекту, из которого запущен Claude Code.

6. Подтверди проектный сервер. При статусе Pending approval запусти Claude Code в этом проекте и подтверди подключение.

7. Проверь URL HTTP-сервера.

   bash

   Скопировать

   curl -I https://example.com/mcp

   Замени адрес на URL подключённого сервера.

8. Проверь stdio-сервер вручную. Запусти команду сервера в терминале и посмотри исходную ошибку. Так можно увидеть проблему пакета, команды или доступа к файлам.

9. Увеличь таймаут для долгого запуска.

   bash

   Скопировать

   MCP_TIMEOUT=60000 claude

10. Проверь режим отладки при пустом списке.

    bash

    Скопировать

    claude --debug mcp

    Отладочный вывод помогает увидеть stderr сервера и причину, по которой tools не загрузились.

Какие ошибки новичка мешают подключению MCP

Проверь типичные промахи:

• MCP не добавляется в .claude/settings.json. Для подключений используются ~/.claude.json и .mcp.json в зависимости от scope.

• Пользовательский scope хранится в ~/.claude.json, а не в случайном файле настроек редактора.

• В CLI забывают разделитель --. Он отделяет параметры Claude Code от команды и аргументов MCP-сервера.

  bash

  Скопировать

  claude mcp add --transport stdio my-tool \
    -- npx -y some-mcp-server

• В JSON пишут servers вместо mcpServers.

  json

  Скопировать

  {
    "mcpServers": {
      "my-tool": {}
    }

• В массиве args объединяют несколько аргументов в одну строку. "mcp serve" должно быть разделено на "mcp" и "serve".

• Относительный путь считают от расположения .mcp.json. На деле он считается от каталога, из которого запущен Claude Code.

  json

  Скопировать

  {
    "mcpServers": {
      "my-tool": {
        "type": "stdio",
        "command": "./tools/my-server"
      }
    }

  Такой путь заработает только при правильном каталоге запуска. Надёжнее использовать абсолютный путь или запускать Claude Code из корня проекта.

• Ждут автоматического вызова инструмента. Для проверки назови сервер в запросе и ищи tool call в выводе.