MCP-серверы в Claude Code: подключение GitHub, баз данных и своих API

MCP-сервер в Claude Code нужен, когда агенту не хватает встроенных инструментов: прочитать задачи в трекере, сделать запрос к базе, открыть pull request. Model Context Protocol — открытый стандарт подключения таких инструментов. Ниже разобраны команды claude mcp, области хранения настроек, два рабочих примера и то, как MCP влияет на расход токенов. Команды и ключи сверены с официальной страницей Claude Code о MCP.

Что такое MCP

MCP (Model Context Protocol) описывает, как AI-приложение общается с внешними сервисами. MCP-сервер предоставляет инструменты (tools), ресурсы и промпты, а Claude Code выступает клиентом. Подключённые инструменты агент вызывает так же, как встроенные Read или Bash. В названиях они выглядят как mcp__<сервер>__<инструмент>.

Транспорты:

• HTTP — удалённый сервер по URL. Документация рекомендует его для облачных сервисов, он поддерживает OAuth;
• stdio — локальный процесс на вашей машине (например, npx-пакет или свой скрипт);
• SSE — устаревший вариант, используйте HTTP, где возможно;
• WebSocket — настраивается только через JSON ("type": "ws").

Работа с файлами и терминалом — это встроенные инструменты Claude Code, а не MCP-серверы. Подключать для этого ничего не нужно.

Как добавить MCP-сервер

Удалённый HTTP-сервер:

claude mcp add --transport http notion https://mcp.notion.com/mcp

С заголовком авторизации:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Локальный stdio-сервер:

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

Всё, что стоит после --, — команда запуска сервера. Без разделителя Claude Code попытается разобрать флаги сервера как свои.

Управление:

claude mcp list
claude mcp get notion
claude mcp remove notion

Внутри сессии команда /mcp показывает статус серверов (connected, failed, требуется авторизация), запускает OAuth-вход и позволяет временно отключить сервер, не удаляя его настройки.

Области: local, project, user

Флаг --scope определяет, где хранится настройка:

Серверы MCP не записываются в ~/.claude/settings.json. Проектный .mcp.json выглядит так:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

В .mcp.json работает подстановка ${VAR} и ${VAR:-значение_по_умолчанию} в полях command, args, env, url и headers. Так секреты остаются в окружении, а не в репозитории. У записи с url обязательно поле type, иначе Claude Code сочтёт её stdio-сервером и пропустит.

Важная деталь безопасности: учётные данные самого Claude Code, включая ANTHROPIC_AUTH_TOKEN, в url и headers удалённых серверов подставляются пустыми. Ключ Zukko не может случайно уйти стороннему MCP-серверу. Если серверу нужен токен, заведите для него переменную со своим именем.

В интерактивной сессии Claude Code спрашивает подтверждение перед использованием серверов из .mcp.json. В режиме claude -p такого вопроса нет, проектные серверы подключаются сразу. Учитывайте это при запуске на чужих репозиториях.

Пример: GitHub

Официальный пример из документации — удалённый сервер GitHub с fine-grained токеном:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Дайте токену доступ только к нужным репозиториям. Проверьте статус через /mcp, затем пишите обычным языком: «Review PR #456 and suggest improvements», «Create an issue for the bug we just found». Никакого специального синтаксиса вызова инструментов в промпте не нужно, агент сам выберет инструмент.

Пример: PostgreSQL

Для баз данных документация приводит сервер DBHub:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/analytics"

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

Свой MCP-сервер

Для своего API проще всего взять официальный SDK MCP (есть для Python и TypeScript). Функции с описанием регистрируются как инструменты, протокол реализует библиотека. Готовый сервер подключается как stdio:

claude mcp add --transport stdio my-api -- python /path/to/server.py

Детали API зависят от версии SDK, поэтому код сервера пишите по документации SDK на modelcontextprotocol.io. Писать JSON-RPC вручную не стоит: нужно корректно пройти инициализацию и согласование возможностей.

MCP и расход токенов при работе через Zukko

Claude Code подключается к Zukko так:

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_ваш_ключ
export ANTHROPIC_MODEL=claude-sonnet-5

Адрес без /v1. Подробнее — в инструкции по Claude Code↗.

Нюанс из документации: когда ANTHROPIC_BASE_URL указывает на сторонний хост, поиск инструментов MCP (tool search) по умолчанию выключен. Тогда описания всех инструментов всех подключённых серверов загружаются сразу и уходят в контекст с каждым запросом. Что из этого следует:

• держите подключёнными только нужные серверы, остальные отключайте в /mcp;
• ответы инструментов тоже идут в контекст. Claude Code предупреждает, когда ответ превышает 10 000 токенов, и по умолчанию обрезает его на 25 000 (лимит меняет MAX_MCP_OUTPUT_TOKENS). Просите агента выбирать узко: фильтр в SQL, конкретный PR, а не всё подряд.

Оценка по формуле. Допустим, описания инструментов занимают 15 000 токенов, а сессия сделала 100 запросов к модели: 15 000 × 100 = 1 500 000 токенов, или 1.5 × $0.3 = $0.45 на claude-sonnet-5 (вход $0.3 за 1M). Оговорка про кэш: у вендора чтение из кэша промптов стоит около 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. Для таких повторяющихся блоков реальная разница с официальным прайсом меньше, чем при прямом сравнении цен. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Ключ для работы создаётся в кабинете Zukko↗. Там же задаются дневной лимит и список разрешённых моделей.

Частые вопросы

Где Claude Code хранит настройки MCP?

Серверы с областью local и user хранятся в ~/.claude.json, серверы project — в .mcp.json в корне проекта.

Что делать, если сервер долго запускается?

Таймаут запуска задаёт переменная MCP_TIMEOUT в миллисекундах, например MCP_TIMEOUT=10000 claude. Статус и ошибку подключения показывает /mcp.

Можно ли подключить несколько серверов сразу?

Да. Жёсткого лимита на число серверов или инструментов документация не задаёт, практический предел — контекст: чем больше инструментов, тем больше токенов уходит на их описания.

Работают ли MCP-серверы в неинтерактивном режиме?

Да. Серверы можно передать флагом --mcp-config. Но OAuth-вход в режиме -p пройти нельзя: авторизуйтесь заранее в интерактивной сессии через /mcp.