# Настройка MCP в Claude Code: как добавить серверы

URL: https://agentvera.dev/ru/blog/claude-code-mcp-setup/ · Опубликовано: 2026-10-28

Как добавить MCP-серверы в Claude Code: claude mcp add для stdio и HTTP, scope, .mcp.json, /mcp и OAuth, импорт из Claude Desktop, тайм-ауты и лимиты вывода.

**Коротко:**

- Сервер добавляется командой claude mcp add: опции идут до имени, а команда локального stdio-сервера — после --. Удалённые серверы добавляются с --transport http и URL.
- Scope определяет, где хранится сервер: local (по умолчанию) и user — в ~/.claude.json, project — в файле .mcp.json в корне репозитория, который можно закоммитить.
- Команда /mcp в сессии показывает статус, выполняет вход на OAuth-серверы и отключает серверы. MCP_TIMEOUT и MAX_MCP_OUTPUT_TOKENS решают большинство проблем с запуском и выводом.
- Claude Code спрашивает разрешения, прежде чем использовать серверы из .mcp.json проекта. Проверяйте их как любой код из репозитория, а токены держите в ссылках ${VAR}, а не в файле.

Чтобы настроить MCP в Claude Code, выполните в терминале `claude mcp add`. Локальный сервер добавляется как `claude mcp add <имя> -- <команда>`, удалённый — как `claude mcp add --transport http <имя> <url>`, а `--scope` определяет, будет ли сервер доступен только вам в этом проекте (`local`, по умолчанию), всей команде через файл `.mcp.json` (`project`) или вам во всех проектах (`user`). Затем введите `/mcp` внутри сессии, чтобы проверить подключение и войти на серверы с OAuth.

В этом руководстве разобран каждый шаг: транспорты, разделитель `--`, переменные окружения и заголовки, scope, ручное редактирование `.mcp.json`, команды `list`, `get` и `remove`, OAuth, импорт из Claude Desktop, тайм-ауты и лимиты вывода, а также то, что стоит проверить, прежде чем доверять серверам проекта. Команды взяты из [документации Claude Code по MCP](https://code.claude.com/docs/en/mcp "Документация Claude Code по MCP") от Anthropic по состоянию на октябрь 2026 года. Если MCP для вас в новинку, начните со статьи [что такое MCP-сервер](/ru/blog/what-is-mcp-server/ "Что такое MCP-сервер"); какие серверы стоит добавить, описано в подборке [лучших MCP-серверов для программирования](/ru/blog/best-mcp-servers-for-coding/ "Лучшие MCP-серверы для программирования").

## Краткая шпаргалка

| Задача | Команда |
| --- | --- |
| Добавить локальный (stdio) сервер | `claude mcp add <имя> -- <команда> [аргументы...]` |
| Добавить удалённый (HTTP) сервер | `claude mcp add --transport http <имя> <url>` |
| Добавить из JSON-фрагмента | `claude mcp add-json <имя> '<json>'` |
| Поделиться с командой | добавить `--scope project` (пишет `.mcp.json`) |
| Использовать во всех проектах | добавить `--scope user` |
| Список серверов и их состояние | `claude mcp list` |
| Подробности об одном сервере | `claude mcp get <имя>` |
| Удалить сервер | `claude mcp remove <имя>` |
| Войти на OAuth-сервер | `/mcp` в сессии или `claude mcp login <имя>` |
| Импорт из Claude Desktop | `claude mcp add-from-claude-desktop` |
| Статус, вход, отключение, переподключение | `/mcp` внутри Claude Code |

Короткие флаги тоже работают: `-t` вместо `--transport`, `-s` вместо `--scope`, `-e` вместо `--env` и `-H` вместо `--header`.

## Выбор транспорта: stdio, HTTP или SSE

[MCP](/ru/glossary/mcp/ "MCP")-сервер подключается к Claude Code одним из трёх способов:

| Транспорт | Что это | Когда использовать |
| --- | --- | --- |
| `stdio` | Локальный процесс, который Claude Code запускает и с которым общается через stdin и stdout | Серверы, запускаемые через `npx`, `uvx`, Docker или собственный скрипт |
| `http` | Удалённый сервер по streamable HTTP | Облачные сервисы: Notion, Sentry, GitHub, Stripe и другие. Anthropic рекомендует его для удалённых серверов |
| `sse` | Server-Sent Events | Только старые удалённые серверы. В документации SSE помечен как устаревший |

`--transport sse` теперь почти не нужен. Начиная с Claude Code 2.1.265, `claude mcp add --transport http` сначала пробует HTTP и сам переключается на SSE, если сервер не принимает HTTP. В более старых версиях указывайте `--transport sse` явно.

## Добавление локального stdio-сервера

Правило, на котором спотыкаются чаще всего: собственные опции Claude Code (`--transport`, `--scope`, `--env`) пишутся **до** имени сервера, а всё после `--` — это команда сервера, которая передаётся без изменений.

```bash
# Базовая форма
claude mcp add [опции] <имя> -- <команда> [аргументы...]

# Playwright через npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Сервер, которому нужен API-ключ в окружении
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

Без `--` флаг сервера вроде `--port 8080` был бы прочитан как опция Claude Code, и команда завершилась бы ошибкой. Ещё одна ловушка из документации: `--env` принимает несколько пар `KEY=value`, поэтому если имя сервера идёт сразу после него, оно читается как очередная пара и отклоняется. Поставьте между ними другую опцию, например `--transport stdio`, как в примере выше.

Claude Code задаёт `CLAUDE_PROJECT_DIR` в окружении каждого stdio-сервера, поэтому сервер может найти корень проекта, не завися от рабочего каталога.

## Добавление удалённого HTTP-сервера

Удалённому серверу вместо команды передаётся URL. Заголовки добавляются через `--header`, если сервер требует API-ключ или bearer-токен:

```bash
# Облачный сервер со входом через OAuth
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"
```

Заголовок, введённый здесь, сохраняется в файле конфигурации открытым текстом. Для всего, чем вы делитесь, лучше подходят OAuth или ссылка `${VAR}` в `.mcp.json` — о ней ниже.

Если в README сервера уже есть готовое JSON-описание, обойдитесь без флагов и вставьте его через `add-json`. Команда принимает объект, который лежал бы внутри `mcpServers`, а не весь файл:

```bash
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
```

## Выбор scope

Каждый `claude mcp add` записывает сервер в один из трёх scope:

| Scope | Флаг | Где хранится | Кому доступен |
| --- | --- | --- | --- |
| Local (по умолчанию) | `--scope local` | `~/.claude.json`, под путём этого проекта | Только вам, только в этом проекте |
| Project | `--scope project` | `.mcp.json` в корне проекта | Всем, кто клонирует репозиторий |
| User | `--scope user` | `~/.claude.json` | Только вам, во всех проектах |

```bash
claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
```

Простое правило: личные инструменты и всё, что содержит ваши учётные данные, — в `user` или `local`; серверы, которые нужны всей команде для работы с репозиторием, — в `project`.

Обратите внимание: «local» здесь — это не `.claude/settings.local.json`. Локальные MCP-серверы хранятся в `~/.claude.json` в домашнем каталоге.

Если одно и то же имя определено в нескольких местах, Claude Code берёт самое приоритетное и не объединяет поля: сначала local, затем project, затем user, затем серверы плагинов, затем коннекторы claude.ai. Если два scope связывают одно имя с разными адресами, `claude mcp list` и `/mcp` предупреждают об этом.

## Ручное редактирование .mcp.json

Сервер со scope project — это просто файл `.mcp.json`, который можно править и ревьюить в pull request:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
```

`${VAR}` раскрывается в значение переменной окружения, а `${VAR:-default}` подставляет значение по умолчанию, если переменной нет. Подстановка работает в `command`, `args`, `env`, `url` и `headers` — так файл коммитится без токенов: каждый разработчик задаёт `API_KEY` в своей оболочке. Если переменной нет и значения по умолчанию тоже нет, `claude mcp list` и `/mcp` выдают предупреждение и оставляют текст нераскрытым.

Поле `"timeout"` у отдельного сервера, в миллисекундах, задаёт жёсткий лимит на вызовы инструментов этого сервера.

## Управление серверами: list, get, remove и /mcp

Из оболочки:

```bash
claude mcp list          # все серверы и статус подключения
claude mcp get notion    # подробности об одном сервере, в том числе причина сбоя
claude mcp remove notion # удалить из его scope
```

`list` и `get` показывают подробности ошибки со скрытыми учётными данными. Сервер проекта, который вы ещё не одобрили, отображается как ожидающий, пока вы не запустите `claude` интерактивно и не одобрите его.

Внутри сессии панель управления — это `/mcp`. Она показывает статус и число инструментов каждого сервера, а в меню сервера можно пройти аутентификацию, пройти её заново, сбросить её, переподключиться или отключить сервер, не удаляя конфигурацию. `/mcp reconnect all` разом переподключает все упавшие серверы (Claude Code 2.1.284 и новее).

Подключённые серверы дают не только инструменты. Введите `@`, чтобы сослаться на ресурсы сервера рядом со своими файлами, и `/`, чтобы увидеть его промпты в виде `/servername:promptname (MCP)`. Сами инструменты называются `mcp__<сервер>__<инструмент>` — это имя используется в правилах разрешений и в [matcher’ах хуков](/ru/blog/claude-code-hooks-guide/ "Руководство по хукам Claude Code").

## Вход на OAuth-серверы

Многие облачные серверы, например Sentry, Notion или Linear, используют OAuth вместо статического токена. Добавьте сервер с `--transport http` без заголовков, а затем войдите:

```bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

В Claude Code выполните `/mcp`, выберите сервер и нажмите **Authenticate**. Откроется браузер, вы войдёте, а Claude Code сохранит токен и будет его обновлять. То же самое можно сделать из оболочки, не открывая сессию:

```bash
claude mcp login sentry               # открывает браузер
claude mcp login sentry --no-browser  # печатает URL, для SSH-сессий
claude mcp logout sentry              # удаляет сохранённые учётные данные
```

Headless-запуски (`claude -p`) не могут показать окно входа, поэтому сначала один раз войдите интерактивно. Некоторым серверам нужен фиксированный callback-порт или заранее зарегистрированное OAuth-приложение; для них при добавлении сервера передайте `--callback-port`, `--client-id` и `--client-secret`. Секрет запрашивается со скрытым вводом или читается из `MCP_CLIENT_SECRET` в CI.

## Импорт серверов из Claude Desktop

Если серверы уже настроены в приложении Claude Desktop, вводить их заново не нужно:

```bash
claude mcp add-from-claude-desktop
```

В открывшемся диалоге выбираются серверы для импорта. По состоянию на октябрь 2026 года это работает только на macOS и в WSL. Добавьте `--scope user`, чтобы импортировать их в пользовательскую конфигурацию. Имена серверов могут содержать только буквы, цифры, дефисы и подчёркивания, поэтому сервер Desktop с пробелом в имени пропускается с сообщением, а уже существующее имя получает суффикс вроде `server_1`.

## Устранение неполадок

| Симптом | Что попробовать |
| --- | --- |
| Сервер не подключается | `claude mcp get <имя>`, чтобы увидеть ошибку, затем **Reconnect** в `/mcp` |
| Медленный сервер падает по тайм-ауту при запуске | Запустить `MCP_TIMEOUT=10000 claude` (десять секунд) |
| Долгие вызовы инструментов обрываются | `MCP_TOOL_TIMEOUT` для всех серверов или `"timeout"` для отдельного сервера в `.mcp.json` |
| Предупреждение о выводе или обрезанные результаты | Claude Code предупреждает после 10 000 токенов и по умолчанию обрезает на 25 000. Поднять через `MAX_MCP_OUTPUT_TOKENS=50000` |
| Флаги сервера игнорируются или отклоняются | Опции Claude Code — до имени, команда сервера — после `--` |
| Предупреждение о `${VAR}` в `/mcp` | Задать переменную в оболочке, из которой запускается Claude Code, или добавить `:-default` |
| Сервер пропускается при загрузке | Имя зарезервировано (`workspace`, `claude-in-chrome`, `computer-use` и ещё несколько); переименуйте |
| Токен работает в curl, но не здесь | Проверьте пробел или перевод строки в конце вставленного токена; Claude Code предупреждает о скрытых пробельных символах |

У длинных текстовых результатов есть второй лимит: результат длиннее 50 000 символов сохраняется в файл, а не попадает напрямую в контекст.

Удалённые серверы, отвалившиеся посреди сессии, переподключаются до пяти раз с растущей паузой, а stdio-серверы автоматически не перезапускаются, так что упавший локальный сервер нужно переподключить из `/mcp`.

Второй ресурс, за которым стоит следить, — контекст. На актуальных моделях Claude Code по умолчанию использует поиск инструментов (tool search): при запуске загружаются только имена инструментов и инструкции серверов, а полные определения — когда они понадобятся Claude. Поэтому длинный список серверов обходится дёшево, но каждый сервер — это ещё одна деталь, которая может сломаться или быть использована во вред, так что держите список коротким. В скриптах `--mcp-config <файл>` подгружает дополнительные серверы на один запуск, а `--strict-mcp-config` заставляет Claude Code использовать только их.

## Безопасность: серверы проекта — это код из репозитория

`.mcp.json` в репозитории может запустить любую локальную команду или указать на любой URL. Именно это делает его полезным для команд, и именно поэтому Claude Code обращается с ним осторожно:

- **Сначала одобрение.** В интерактивной сессии Claude Code спрашивает, прежде чем использовать серверы со scope project. `claude mcp reset-project-choices` сбрасывает ваши прошлые ответы.
- **Репозиторий не может одобрить сам себя.** Настройки вроде `enableAllProjectMcpServers`, закоммиченные в `.claude/settings.json` проекта, игнорируются, пока вы не доверяете папке, и сервер остаётся в ожидании. Одобрения из ваших собственных пользовательских настроек по-прежнему действуют.
- **Headless-запуски не спрашивают.** В `claude -p` и в Agent SDK запроса нет, поэтому серверы проекта загружаются без него. Чтобы заблокировать сервер в любом режиме, внесите его в `disabledMcpjsonServers`.
- **Учётные данные остаются дома.** В полях `url` и `headers` удалённого сервера чувствительные переменные вроде `ANTHROPIC_API_KEY` раскрываются в пустую строку, даже если заданы, поэтому проект не может тихо отправить ваш ключ Anthropic на свой сервер.
- **Доверяйте тому, что сервер возвращает, так же мало, как тому, что он запускает.** Документация Anthropic предупреждает, что серверы, получающие внешний контент, могут подвергнуть вас [prompt injection](/ru/glossary/prompt-injection/ "Prompt injection"). Выбирайте режимы только для чтения и токены с минимальными правами.

Перед одобрением прочитайте `command`, `args` и `url` каждого сервера так же внимательно, как скрипт `postinstall`. Общая картина — в статье о [безопасности ИИ-агентов для программирования](/ru/blog/ai-coding-agent-security/ "Безопасность ИИ-агентов для программирования").

## Если вы работаете не только с Claude Code

Всё описанное выше относится к одному CLI. Codex хранит свои серверы в `~/.codex/config.toml`, Gemini CLI — в собственном `settings.json`, и у каждого инструмента свои команды. Если Claude Code — ваш единственный агент, `claude mcp add` и закоммиченного `.mcp.json` вполне достаточно, и ничего здесь не требует другого инструмента.

Если вы запускаете несколько CLI для программирования, списки серверов со временем расходятся. Для этого и сделан [MCP-менеджер](/ru/features/mcp-manager/ "MCP-менеджер") в AgentVera — десктопном приложении, которое издаёт этот блог:

- **Добавлен один раз, подключается при запуске.** Вы регистрируете stdio-, HTTP- и SSE-серверы в AgentVera, и они подключаются при старте агентов: ко всем агентам, к выбранным, к агентам группы или к роли в команде. Их получают Claude Code, Codex и другие CLI-агенты с поддержкой MCP.
- **В согласии с конфигурацией Claude Code.** Серверы из настроек Claude Code и Codex отображаются вместе с их состоянием; их можно импортировать в AgentVera или удалить из CLI, а серверы AgentVera можно записать в настройки CLI.
- **Один вход, никаких токенов в файлах.** Удалённые серверы идут через шлюз AgentVera, вход на OAuth-сервер выполняется один раз в приложении, и CLI агента не хранит ни заголовков, ни токенов. Секретные переменные окружения и заголовки хранятся в связке ключей операционной системы.
- **Видимая стоимость.** Проверка подключения показывает инструменты, промпты и ресурсы сервера с примерной стоимостью в токенах для каждого инструмента.

## Итог

Начните с одного действительно нужного сервера, добавленного через `claude mcp add` в самом узком подходящем scope. Проверьте его через `claude mcp list` или `/mcp`, войдите через `/mcp` или `claude mcp login`, а в закоммиченный `.mcp.json` переносите его, только когда он нужен всей команде, и с токенами в ссылках `${VAR}`. Когда что-то ломается, большую часть проблем решают `claude mcp get`, `MCP_TIMEOUT` и `MAX_MCP_OUTPUT_TOKENS`.

Читайте также:

- [Что такое MCP-сервер?](/ru/blog/what-is-mcp-server/ "Что такое MCP-сервер")
- [Лучшие MCP-серверы для агентов программирования](/ru/blog/best-mcp-servers-for-coding/ "Лучшие MCP-серверы для программирования")
- [MCP-менеджер](/ru/features/mcp-manager/ "MCP-менеджер")
- [Агент Claude Code](/ru/agents/claude-code/ "Claude Code в AgentVera")

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

**Как добавить MCP-сервер в Claude Code?** Выполните claude mcp add в терминале. Для локального сервера: claude mcp add <имя> -- <команда> [аргументы]. Для удалённого: claude mcp add --transport http <имя> <url>. Затем проверьте подключение через claude mcp list или /mcp внутри сессии.

**Где Claude Code хранит MCP-серверы?** Серверы со scope local (по умолчанию) и user хранятся в ~/.claude.json, причём local — под путём текущего проекта. Серверы со scope project лежат в файле .mcp.json в корне проекта, и его можно закоммитить для команды.

**Чем отличаются scope local, project и user?** Local — только для вас и только в этом проекте. Project — для всех, кто клонирует репозиторий, через .mcp.json. User — только для вас, но во всех проектах на машине. Если одно имя есть в нескольких scope, local важнее project, а project важнее user.

**Как войти на MCP-сервер, который использует OAuth?** Добавьте его с --transport http, затем выполните /mcp в Claude Code и выберите Authenticate или запустите claude mcp login <имя> из оболочки. Вход в браузере завершает процесс, а Claude Code сам хранит и обновляет токен.

**Почему MCP-сервер падает по тайм-ауту или обрезает вывод?** Медленному серверу может не хватать времени на запуск: запустите Claude Code с MCP_TIMEOUT=10000, это десять секунд. Вывод инструментов по умолчанию ограничен 25 000 токенов, предупреждение появляется после 10 000; лимит поднимается через MAX_MCP_OUTPUT_TOKENS.

**Безопасен ли .mcp.json из клонированного репозитория?** Относитесь к нему как к любому чужому коду. В интерактивной сессии Claude Code запрашивает подтверждение перед использованием серверов проекта, а клонированный репозиторий не может одобрить собственные серверы. Прочитайте каждую команду и URL, прежде чем соглашаться.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/