раздел 07 · подстраница 2

Где живёт конфиг

MCP-серверы регистрируются в одном из трёх файлов в зависимости от scope. Знать их полезно для отладки, ручных правок и шеринга конфигов с командой.

Зачем

claude mcp add - удобно, но иногда надо ручками: поправить env-vars, перенести сервер из local в project, отдать конфиг коллеге. Все эти файлы - простой JSON, открываются в любом редакторе.

Три файла

| Scope | Путь | Коммитим? | | --------- | ----------------------------------------- | --------- | | user | ~/.claude.json | Нет | | project | <project>/.mcp.json | Да | | local | <project>/.claude/settings.local.json | Нет |

Структура .mcp.json

Проектный файл - самый чистый. Только MCP, ничего лишнего:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${POSTGRES_URL}"
      }
    },
    "company-api": {
      "type": "http",
      "url": "https://mcp.company.com/api",
      "headers": {
        "Authorization": "Bearer ${COMPANY_API_TOKEN}"
      }
    }
  }
}

Поля

  • type - stdio или http. Для stdio нужны command + args. Для http - url.
  • command - исполняемый файл: npx, python3, node, или путь к скрипту.
  • args - массив аргументов.
  • env - объект с переменными для подпроцесса.
  • url - для http-серверов.
  • headers - дополнительные заголовки для http.

Подстановка переменных окружения

В значениях env, args, url, headers работает синтаксис ${VAR_NAME}. Подставляется из shell в момент запуска Claude.

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Это позволяет коммитить .mcp.json в git без утечки токенов: у каждого участника команды свой GITHUB_TOKEN в shell.

Структура ~/.claude.json (user scope)

Это огромный файл, но интересует только секция mcpServers:

{
  "userId": "...",
  "projects": { "...": {} },
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

В user-scope можно хардкодить токены - файл не в git. Но всё равно безопаснее через ${VAR}.

settings.local.json (local scope)

{
  "mcpServers": {
    "experimental": {
      "type": "stdio",
      "command": "python3",
      "args": ["./my-mcp.py"]
    }
  }
}

Этот файл - в .gitignore. Туда удобно класть экспериментальные серверы, которые вы тестируете локально, прежде чем переносить в project scope.

Иерархия

При старте Claude собирает MCP-серверы из всех трёх файлов в одну общую таблицу. Если в двух файлах есть сервер с одинаковым именем - побеждает более узкий scope: local > project > user.

Удобно для отладки: можно "затемнить" production-сервер локальной версией, не трогая .mcp.json команды.

Как менять без перезапуска Claude

  1. Отредактировать файл (любой из трёх).
  2. В чате: /mcp -> там есть пункт "Reconnect all" или можно дёрнуть отдельный сервер.
  3. Если меняли env через shell - перезапуск Claude всё-таки нужен (новый shell-окружение читается только при старте).

Полный пример: командный .mcp.json

.mcp.json в корне проекта admin.pavel-doronin.com:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

И README.md с инструкцией:

## MCP-серверы

Добавьте в `~/.zshrc`:

\`\`\`bash
export GITHUB_TOKEN=ghp_...
\`\`\`

После клонирования - в репо запустите `claude`. MCP-серверы подхватятся из `.mcp.json` автоматически.

Антипаттерны

  • Хардкод токенов в .mcp.json - один git push и они в публичном репо.
  • Дублировать сервер в user и project с одним именем - сложно понять, какой реально используется.
  • Менять ~/.claude.json руками целиком - там много служебных полей, легко сломать. Лучше через claude mcp add/remove.
  • Не добавлять .mcp.json в gitignore.example, если используете local-only паттерн - команда будет создавать его каждый раз.

Полезные ссылки