MCP vs API в Claude Code: что выбрать и подключить для первого теста

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

Представь задачу: найти issue, проверить мониторинг, прочитать данные из базы или открыть страницу в браузере. Сам Claude Code работает с файлами и командами в текущем окружении. Но внешний сервис живёт отдельно. Между ними появляется понятный канал связи MCP.

У MCP две стороны:

• внешний источник или сервис;
• AI-приложение, в данном случае Claude Code.

Сервер MCP может работать без отдельного удалённого компьютера. Он запускается локально как процесс на твоём компьютере. Такой вариант подходит для файлов, локального Git-репозитория или скрипта. Удалённый сервер подключается по HTTP и работает как внешний сервис.

Самая полезная граница простая. Если Claude Code уже умеет выполнить задачу через файлы, shell-команду или CLI, MCP не обязателен. Если нужная система живёт отдельно и удобного CLI нет, MCP становится удобным способом дать к ней доступ.

Что Claude Code получает после подключения MCP?

Важно различать данные и действия.

Данные - это то, что Claude может прочитать:

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

Действия - это то, что Claude может сделать:

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

Документация Claude Code перечисляет такие сценарии:

Например, Filesystem даёт доступ к указанной папке. Memory хранит локальный граф сущностей и связей. Браузерный сервер открывает страницы и возвращает результаты. Сервер конкретного SaaS может дать сразу поиск, чтение, создание и изменение объектов.

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

Я для первого теста беру сервер с результатом, который легко проверить глазами. Прочитать файл, записать факт в Memory или показать список доступных инструментов проще, чем сразу подключать рабочую базу.

Как связаны MCP client, MCP server и Claude Code?

Три роли можно держать в голове так:

• Claude Code - приложение, где ты пишешь запрос;
• MCP client - встроенная часть Claude Code, которая держит соединение;
• MCP server - прослойка, которая предоставляет инструменты;
• внешняя система - файлы, база, API, браузер или рабочий сервис.

Ты пишешь: «Найди открытые issues». Claude Code понимает задачу и выбирает доступный инструмент. Клиент отправляет вызов MCP-серверу. Сервер обращается к GitHub или другой системе. Результат возвращается в Claude Code, а затем модель формирует ответ.

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

Локальный сервер запускается как процесс на компьютере. Удалённый сервер доступен по URL. Для Claude Code это разные способы добраться до одного результата: получить инструмент и вызвать его.

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

Я проверял оба подхода. API - это прямой путь к конкретному сервису. Чтобы получить список задач, приложение отправляет заранее известный запрос. При создании задачи оно отправляет другой запрос. Логику этих вызовов кто-то должен прописать заранее.

MCP добавляет слой, который делает инструменты видимыми для AI-приложения. Claude Code получает их описания и выбирает нужное действие по тексту задачи.

MCP не заменяет API внутри сервиса. Часто MCP-сервер сам обращается к API. Разница в уровне подключения:

• API даёт прямой программный доступ;
• MCP упаковывает доступные действия в формат, с которым работает AI-приложение.

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

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

Что выбрать новичку: MCP, API или встроенный инструмент?

Правило из документации Anthropic звучит ещё короче:

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

Если не знаешь, с чего начать, выбери локальный Filesystem. Он даёт понятный результат и ограничивает доступ одной папкой.

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

Какие MCP-серверы подходят для первого теста?

Filesystem

Filesystem - самый понятный старт. Сервер получает путь к разрешённой папке. Доступ ко всему компьютеру ему не предоставляется.

mkdir -p mcp-demo
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

Создай файл и запусти Claude Code:

echo "MCP works" > mcp-demo/test.txt
claude

Проверочный запрос:

Прочитай mcp-demo/test.txt и скажи, что в нём написано.

Официальная коллекция MCP-серверов показывает тот же принцип: путь к разрешённой папке передаётся серверу аргументом. GitHub - Model Context Protocol Servers

Everything

Everything нужен для проверки самого подключения:

claude mcp add everything -- npx -y @modelcontextprotocol/server-everything

После запуска попроси:

Покажи, какие инструменты и ресурсы доступны через сервер everything.

Репозиторий прямо называет Everything тестовым сервером, который служит для проверки. README Everything

Memory

Memory хранит локальный граф сущностей и связей:

claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

Проверка:

Запомни: в этом проекте цвет кнопок должен быть оранжевым.

В новом запросе:

Какой цвет кнопок используется в этом проекте?

Для GitHub нужен Personal Access Token. Google Workspace требует Google Cloud и OAuth. PostgreSQL требует уже работающую базу, поэтому эти варианты подойдут для следующего этапа.

Что нужно установить перед подключением MCP?

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

node --version
npx --version
claude --version

Filesystem запускается через npx, поэтому без Node.js команда не сработает. Git-сервер использует локальный репозиторий и uvx. Если выбранный сервер требует отдельную базу, браузер или аккаунт, одной установки Claude Code недостаточно.

Проверь текущую папку:

pwd
ls

Для Filesystem папка может быть создана прямо перед тестом:

mkdir -p mcp-demo

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

Если Node.js установлен через NVM, Claude Code может увидеть другой PATH, чем терминал. Тогда node или npx не найдутся. Проверь путь:

which node
which npx

При нестабильном окружении используй абсолютный путь к исполняемому файлу.

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

1. Создай отдельную папку теста.

   Так результат не смешается с рабочими файлами.

   bash

   Скопировать

   mkdir -p mcp-demo
   echo "MCP works" > mcp-demo/test.txt

   Папка нужна и для проверки доступа Filesystem, и для понимания текущего проекта.

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

   Команда передаёт серверу только разрешённую папку.

   bash

   Скопировать

   claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

   -- отделяет параметры Claude Code от команды, которая запускает MCP-сервер.

3. Проверь список серверов.

   Сначала смотри состояние вне интерактивной сессии.

   bash

   Скопировать

   claude mcp list

   Нужный результат:

   Скопировать

   ✔ Connected

   Другие статусы тоже полезны. Needs authentication означает, что сервер доступен, но ждёт входа или токен. Failed to connect означает, что сервер не ответил. Pending approval означает, что проектный сервер ещё не одобрен.

4. Запусти Claude Code заново.

   Полный перезапуск нужен после изменения .mcp.json или конфигурации проекта.

   bash

   Скопировать

   claude

   Если Claude Code уже был открыт во время добавления сервера, закрой текущую сессию и запусти её снова.

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

   Эта команда показывает настроенные серверы, статус соединения и одобрение проекта.

   Скопировать

   /mcp

   Убедись, что filesystem виден в списке. Если сервер проектный, здесь может появиться действие для одобрения.

6. Попроси использовать нужный сервер.

   Не проверяй MCP вопросом, который Claude легко решит встроенным инструментом.

   Проверка Filesystem MCPСкопировать промпт

   Используй filesystem MCP.
   Прочитай файл mcp-demo/test.txt через этот сервер.
   Не используй встроенный Glob или чтение файла напрямую.
   Скажи точный текст файла.

   В ответе должен появиться реальный вызов инструмента Filesystem и текст MCP works.

7. Добавь удалённый сервер отдельно.

   Для HTTP-сервера не нужен локальный процесс, но нужен URL.

   bash

   Скопировать

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

   Затем проверь список:

   bash

   Скопировать

   claude mcp list

8. Открой удалённый сервер через `/mcp`.

   Если сервер требует вход, выбери его и выполни Authenticate.

   Скопировать

   /mcp

   После OAuth попроси Claude обратиться именно к этому серверу:

   Скопировать

   Используй сервер claude-code-docs и найди, что делает переменная MCP_TIMEOUT.

9. Проверь локальный процесс напрямую.

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

   bash

   Скопировать

   npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

   Для stdio-сервера такой запуск помогает увидеть ошибку npx, Node.js, пути или обязательной переменной окружения.

10. Зафиксируй рабочую команду.

    После успешного теста запиши имя сервера, scope и способ запуска в заметку проекта.

    Скопировать

    filesystem
    local
    npx -y @modelcontextprotocol/server-filesystem

    Не добавляй рабочие токены в такую заметку. Секреты храни через переменные окружения, OAuth или заголовки.

Где хранится настройка MCP и какой scope выбрать?

Локальный тест:

claude mcp add --scope local filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

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

claude mcp add --scope user memory -- npx -y @modelcontextprotocol/server-memory

Командная конфигурация:

claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

Проектный сервер лежит в .mcp.json. Не клади его в .claude/settings.json: это другой файл и другая настройка.

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

Сколько инструментов подключать, чтобы не раздувать контекст?

Anthropic описывает агентов с сотнями и тысячами инструментов через десятки MCP-серверов. Такой масштаб возможен, но он не бесплатен для контекста.

Большой набор создаёт две проблемы:

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

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

Если работаешь с файлами, не добавляй одновременно браузер, GitHub, базу и несколько серверов памяти без задачи. Сначала проверь один сценарий. Потом добавляй следующий сервер и снова проверяй список инструментов.

Почему MCP подключён, но Claude его не использует?

Симптом выглядит обманчиво: статус Connected есть, но в ответе нет вызова MCP.

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

Проверяй в два этапа:

1. Открой /mcp и убедись, что сервер подключён.
2. Отправь запрос, где MCP нужен явно.

Используй filesystem MCP.
Прочитай mcp-demo/test.txt именно через инструмент filesystem.
Не используй встроенный Grep, Glob, Bash или прямое чтение файла.
Покажи результат вызова и точный текст файла.

Если инструмент должен вызываться всегда при событии, MCP сам по себе не даёт такой гарантии. Для обязательного вызова в фактуре указан hook с типом mcp_tool.

Не считай отсутствие вызова доказательством поломки. Сначала проверь, действительно ли запрос требовал именно MCP.

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

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

1. Проверь текущий проект:

pwd
ls -la

claude mcp add мог быть выполнен в другой папке. Проектный сервер привязан к текущему проекту.

2. Загляни в файл:

ls -la .mcp.json

Проектная конфигурация должна лежать в корне проекта. Не ищи её в .claude/settings.json.

3. Перезапусти сессию:

exit
claude

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

4. Проверь удалённый URL:

claude mcp list

Статус Failed to connect говорит о том, что сервер или URL не ответил. Needs authentication указывает на необходимость авторизации.

5. Запусти локальную команду напрямую:

npx -y @modelcontextprotocol/server-filesystem "$PWD/mcp-demo"

Так ошибка становится видимой до уровня MCP. Команда может не найти Node.js, пакет или обязательную переменную.

6. Проверь окружение:

which node
which npx
which uvx
echo "$PATH"

При NVM приложение может получить другой PATH, чем терминал. В таком случае используй абсолютный путь к node или npx.

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

Если после этого проектный сервер не виден в /mcp, не переноси конфигурацию случайно между Claude Code, Claude Desktop и расширением VS Code. Для расширения нет надёжного универсального исправления в фактуре, поэтому обещать конкретный workaround я не буду.

Как безопасно подключить MCP с OAuth или API-ключом?

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

mcp защита начинается с простых вопросов перед подключением. Проверь:

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

Для OAuth порядок такой:

1. зарегистрируй удалённый сервер;
2. запусти Claude Code;
3. открой /mcp;
4. выбери сервер;
5. пройди вход в браузере;
6. вернись в Claude Code и проверь статус.

Регистрация ещё не означает, что вход выполнен. Сервер может отображаться как Needs authentication, пока ты не завершишь OAuth.

API-ключ не зашивай прямо в общий проектный файл. Документация предупреждает:

Для локального сервера переменную можно передать через команду:

claude mcp add my-service -e API_KEY="$API_KEY" -- npx -y example-mcp-server

Для общей конфигурации используй ${VAR}, OAuth или персональные заголовки. Не коммить ключ в .mcp.json.

Нужно ли новичку создавать собственный MCP-сервер?

Готовые подключения уже есть для разных сценариев. Anthropic направляет к Directory, где можно искать reviewed connectors, но сам каталог не заменяет проверку доверия.

Сначала попробуй:

• Filesystem для папки;
• Memory для локальных фактов;
• Git для локального репозитория;
• Everything для проверки протокола;
• готовый сервер нужного SaaS;
• удалённый сервер с OAuth, если сервис его поддерживает.

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

Google Workspace показывает цену готовой интеграции: нужны Google Cloud и OAuth-настройки. PostgreSQL требует работающую базу. Если подходящего готового подключения нет, собственный сервер может оказаться оправдан. Но сначала зафиксируй, какой конкретно инструмент нужен, и проверь Directory.

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