Scopes MCP — local, project, user

Почему это важно именно вам

Когда вы подключаете MCP-сервер к Claude Code — например, доступ к корпоративной базе данных или интеграцию с Notion — первый вопрос не «как?», а «куда?». Куда именно прописать этот сервер. Ответ зависит от того, кто должен его видеть и использовать.

Представьте: у вас есть токен для подключения к базе контрагентов. Этот токен личный — он на ваше имя, с вашими правами доступа. Прописать его в общий конфиг проекта, который потом попадёт в git и окажется у всей команды — это не просто неудобно, это проблема с безопасностью. С другой стороны, если вы подключаете инструмент для работы с базой знаний отдела, который должен быть у всех — прятать его у себя в личных настройках не имеет смысла: тогда коллеги не смогут им пользоваться.

Есть и третья ситуация, которую часто не замечают до первой ошибки: вы хотите попробовать новый сервер в конкретном проекте, но не готовы раскатывать его на всю команду и на все свои проекты. Нужна промежуточная зона — «только у меня, только здесь». Именно её закрывает local scope.

Именно это регулирует понятие scope в MCP. Три варианта — local, project, user — отвечают на три разных вопроса: это для меня и только здесь, это для всех в этом проекте, или это для меня везде. Звучит просто, но на практике большинство ошибок с MCP связаны именно с тем, что сервер прописан не туда. Разберём каждый вариант на конкретных примерах.

Что это такое

Scope — это область видимости MCP-сервера. Где хранится запись о нём и кто её видит.

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

В Claude Code так же:

user — личные настройки, хранятся в ~/.claude.json на вашем компьютере. Этот файл не синхронизируется с git, не уходит коллегам. MCP-серверы в user scope доступны во всех проектах, которые вы открываете, но только вам.

project — настройки проекта, хранятся в файле .mcp.json в корне проекта. Этот файл обычно добавляется в git и уходит ко всем, кто работает с этим репозиторием. MCP-серверы в project scope видят все участники проекта.

local — локальные настройки конкретного проекта, хранятся в ~/.claude.json, но привязаны к пути проекта. Важный момент: local — это не отдельный файл в проекте, а запись в вашем личном ~/.claude.json с указанием, к какому пути она относится. В git не попадает. MCP-сервер виден только вам и только в этом проекте.

Local — не «локальный файл», а «личный для этого проекта»

Это самый часто понимаемый неправильно scope. Local хранится в вашем личном ~/.claude.json, а не в папке проекта. В git он не попадёт, но и на другом компьютере не появится. Это пересечение «personal» и «project-specific».

Как работает на практике

Когда вы добавляете MCP-сервер командой claude mcp add, вы указываете scope флагом --scope. Если флаг не указан, по умолчанию используется local.

Добавление сервера в user scope — для себя, для всех проектов:

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

Что происходит: Claude Code записывает конфигурацию этого сервера в ~/.claude.json с пометкой user. Теперь в любом проекте, который вы откроете, сервер notion-server будет доступен. Коллеги его не видят — это ваши личные настройки.

Добавление сервера в project scope — для всей команды:

claude mcp add --scope project contractor-db -- npx -y @company/contractor-mcp-server

Что происходит: Claude Code создаёт или обновляет файл .mcp.json в текущей директории. Этот файл выглядит примерно так:

{
  "mcpServers": {
    "contractor-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@company/contractor-mcp-server"]
    }
  }
}

Когда коллега откроет этот проект и запустит Claude Code — он увидит тот же сервер. Файл .mcp.json нужно добавить в git командой git add .mcp.json, иначе он останется только у вас.

Токены и пароли — никогда в .mcp.json

Если MCP-сервер требует токен доступа (а большинство реальных серверов требуют), передавайте его через переменные окружения, не в самом файле. Запись "env": {"API_TOKEN": "sk-real-token"} в .mcp.json, который уйдёт в git — это утечка данных. Правильный подход — "env": {"API_TOKEN": "${CONTRACTOR_API_TOKEN}"}, а сам токен каждый разработчик прописывает у себя в ~/.zshenv или аналоге.

Добавление сервера в local scope — для себя, только в этом проекте:

claude mcp add --scope local analytics-db -- npx -y @company/analytics-mcp-server

Или без флага — результат тот же, local используется по умолчанию:

claude mcp add analytics-db -- npx -y @company/analytics-mcp-server

Что происходит: запись уходит в ~/.claude.json, привязанная к текущему пути проекта. В другом проекте этот сервер не появится. Коллеги его не видят.

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

claude mcp list

Вывод покажет все серверы, доступные в текущем контексте, и их scope:

contractor-db (project): npx -y @company/contractor-mcp-server
analytics-db (local): npx -y @company/analytics-mcp-server
notion-server (user): npx -y @modelcontextprotocol/server-notion

Удалить сервер:

claude mcp remove contractor-db --scope project

Обычно достаточно claude mcp remove <имя>. Флаг --scope нужен, только если сервер с таким именем есть сразу в нескольких скоупах: тогда команда ответит exists in multiple scopes и попросит уточнить.

Приоритет при конфликте имён

Если сервер с одним и тем же именем прописан в нескольких скоупах — побеждает local, затем project, затем user, затем серверы из плагинов и коннекторы claude.ai. Побеждает запись целиком: поля из разных скоупов не смешиваются. На практике лучше не создавать конфликтующих имён: это источник путаницы, особенно когда через месяц вы забудете, что прописывали.

Реальный пример — директор и три сервера одновременно:

Допустим, вы работаете с двумя проектами: аналитика по клиентам и внутренний регламент компании.

Для аналитического проекта вы подключаете:
- CRM-сервер через project scope (вся команда работает с CRM одинаково, токен передаётся через env-переменную, у каждого свой)
- Ваш личный сервер для работы с таблицами через local scope (только вы используете этот способ работы с данными, остальные предпочитают другое)

Для регламентного проекта вы подключаете:
- Сервер Notion через user scope (ваш аккаунт, ваш токен, вы работаете с Notion во всех проектах подряд)

Итого: когда вы открываете аналитический проект — Claude видит три сервера (CRM project + ваш local + Notion user). Когда открываете регламентный — только один (Notion user). Когда ваш коллега открывает аналитический проект — видит один (CRM project, потому что local и user — ваши личные).

Это и есть практическая польза трёх scope: каждый получает именно те инструменты, которые нужны, в нужном контексте.

Частые ошибки

Ошибка 1: личный токен в project scope.

Сценарий: подключаете MCP-сервер к CRM с вашим личным OAuth-токеном и добавляете его в .mcp.json, который уходит в git. Коллеги получают ваш токен и доступ от вашего имени — это нарушение безопасности и потенциально нарушение политики доступа.

Как правильно: серверы с личными токенами — только в user или local scope. Если сервер нужен всей команде — в project scope, но токен передаётся через переменную окружения, которую каждый прописывает сам.

Ошибка 2: забыть добавить .mcp.json в git.

Сценарий: вы добавили сервер с --scope project, он работает у вас. Коллега клонирует репозиторий — сервера нет. Жалуется, что Claude не видит базу знаний. Вы не понимаете почему, потому что у вас всё работало.

Как проверить: после claude mcp add --scope project ... сразу запустите git status — .mcp.json должен быть в списке изменённых файлов. Если его там нет — что-то пошло не так. Добавьте в следующий коммит.

Ошибка 3: думать, что local — это файл в папке проекта.

Сценарий: вы ожидаете найти что-то вроде .claude-local.json в папке проекта — как .mcp.json. Ищете, не находите. Думаете, что настройки не сохранились.

Как на самом деле: local хранится в вашем домашнем ~/.claude.json. Проверить можно так:

cat ~/.claude.json | python3 -m json.tool | grep -A5 "local"

Или просто claude mcp list — если сервер отображается как local, значит запись есть.

Ошибка 4: считать, что при удалении всегда нужен --scope.

Сценарий: запускаете claude mcp remove my-server без --scope. Уточнять уровень нужно только при совпадении имён в разных скоупах — и тогда команда честно об этом скажет, ничего лишнего не удалив.

Как правильно: всегда указывайте --scope при удалении. Это занимает две секунды, но избавляет от путаницы.

Ошибка 5: переносить проект на новый компьютер и обнаружить, что часть серверов исчезла.

Сценарий: вы переходите на новый ноутбук, копируете папку проекта с .mcp.json, всё вроде бы перенесено. Запускаете Claude Code — часть серверов есть, часть нет.

Что произошло: серверы в project scope сохранились (они были в .mcp.json в папке проекта). Серверы в local и user scope пропали — они хранились в ~/.claude.json на старом компьютере, который вы не перенесли.

Как правильно: при переносе рабочей среды на новый компьютер нужно перенести и ~/.claude.json. Или заново добавить личные серверы через claude mcp add. Это не баг архитектуры — это намеренное поведение: личные настройки привязаны к машине, не к проекту.

~/.claude.json содержит не только MCP-серверы

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

Когда нужно / когда нет

User scope нужен когда:
- Токен принадлежит лично вам (ваш аккаунт в Notion, ваш API-ключ, ваш доступ к базе)
- Сервер полезен во всех проектах, а не только в одном (например, сервер для работы с файлами или личный органайзер)
- Вы работаете один и командной синхронизации не нужно

Project scope нужен когда:
- Инструмент относится к конкретному проекту и должен быть у всей команды
- Сервер не требует личных токенов — или токены передаются через env-переменные, которые каждый настраивает сам
- Нужно зафиксировать инструменты проекта в версионном контроле (чтобы через год было понятно, какая инфраструктура использовалась)

Local scope нужен когда:
- Вы хотите подключить что-то только для себя в чужом проекте, не меняя общий .mcp.json
- Тестируете новый MCP-сервер перед тем, как добавить его в project scope
- Серверу нужен ваш личный токен, но он нужен только в контексте этого проекта

Не нужно думать о scope когда:
- Вы работаете в одиночку и у вас один проект — тогда разница между local и user почти несущественна
- MCP-сервер — это однократный эксперимент, который вы удалите через час

Стратегия выбора scope — две простых вопроса

Первый: «Этот токен/доступ принадлежит мне лично?» — если да, никогда не project. Второй: «Этот инструмент нужен только в этом проекте или везде?» — если только здесь, local или project; если везде, user. Большинство решений принимается за пять секунд.

Связь с другими уроками

День 51 («Что такое MCP») — там разобрано, зачем вообще нужен MCP и как он отличается от встроенных инструментов Claude. Если вы ещё не читали — лучше начать оттуда: scope без понимания того, что именно добавляется, теряет смысл.

День 52 («Транспорты MCP: stdio, SSE, HTTP») — разбирает техническую сторону подключения: как MCP-сервер общается с Claude. Scope и транспорт — независимые настройки: вы можете иметь stdio-сервер в user scope и SSE-сервер в project scope. Но знать оба понятия нужно вместе.

День 11 («CLAUDE.md: первый уровень») — CLAUDE.md тоже имеет свою логику уровней (проектный, глобальный), и это похоже на scope. Разница: CLAUDE.md управляет инструкциями для Claude, .mcp.json управляет инструментами. Оба файла могут жить в одном проекте и хорошо сочетаются.

Задание на сегодня

Запустите команду claude mcp list в папке любого проекта, с которым вы работаете. Посмотрите, что отображается и какой у каждого сервера scope. Если список пустой — добавьте один тестовый сервер в user scope командой:

claude mcp add --scope user test-server -- echo hello

Затем снова запустите claude mcp list и убедитесь, что сервер появился с пометкой user. После этого удалите его:

claude mcp remove test-server --scope user

Критерий выполнено: вы видели список серверов с указанием scope и успешно добавили и удалили тестовый сервер.

Резюме

User — личные настройки, ~/.claude.json, доступны во всех проектах, только вам
Project — настройки проекта, .mcp.json в корне, уходят в git, видны всей команде
Local — личные настройки конкретного проекта, ~/.claude.json, в git не попадают, видны только вам
Личные токены — только user или local; командные инструменты без токенов — project
Если одно имя занято в нескольких скоупах, remove попросит уточнить --scope