# Настройка MCP серверов > Полный справочник mcp.json: все поля конфигурации, типы транспортов, режимы одобрения, OAuth и входные переменные. Источник: https://docs.kodik.ru/mcp/configuring Глобальные настройки MCP серверов хранятся в файле `mcp.json` активного профиля. Откройте его из панели Kodik через **MCP Серверы** → **Установленные** → **Настроить MCP Серверы**, или отредактируйте напрямую. В локальном окне файл хранится в локальной директории глобального хранилища Kodik (`…/User/globalStorage/kodik.chat/settings/mcp.json`). Когда окно подключено к удалённому окружению, Kodik использует путь глобального хранилища этого удалённого окружения, чтобы глобальная конфигурация MCP находилась там, где запускаются серверы. MCP серверы рабочей области задаются в `/.kodik/mcp.json` и загружаются только для доверенной рабочей области. Для чата путь в системном промпте следует папке, выбранной для данного диалога. Если эта папка находится внутри доверенной рабочей области IDE (включая размещённые внутри неё worktree), поиск MCP и пути запуска серверов тоже следуют ей. Для внешней папки чат показывает неактивный путь, но не запускает её MCP процессы на основании доверия к рабочей области IDE. MCP серверы из плагинов остаются в файле `//.mcp.json` соответствующего плагина; изменяйте этот файл, а не копируйте сервер в глобальную конфигурацию. Kodik передаёт агенту активные абсолютные пути и эти правила областей конфигурации. Поэтому настройка через агента соответствует текущей среде: сборка для разработки использует данные профиля `code-oss-dev`, установленная версия — данные профиля `.kodik`, удалённое окно — путь конфигурации удалённой среды, а установленные плагины остаются в пользовательской директории плагинов Kodik. Файл парсится как **JSONC** — можно свободно использовать `//` комментарии строк, `/* */` блочные комментарии и замыкающие запятые. ## Верхнеуровневая структура ```jsonc { "servers": { // именованные записи серверов здесь }, "inputs": [ // опционально: переменные, запрашиваемые один раз для секретов/путей ], } ``` > Примечание: верхнеуровневый ключ — `servers`, а не `mcpServers`. Конфигурации, написанные для других инструментов с ключом `mcpServers`, нужно переименовать. ## Поля записи сервера Каждая запись сервера имеет общие поля независимо от типа транспорта. ### Общие поля | Поле | Тип | По умолчанию | Описание | | -------------------------- | ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- | | `disabled` | boolean | `false` | Установите `true`, чтобы деактивировать сервер без удаления | | `timeout` | число (секунды) | 60 | Время ожидания ответа на вызов инструмента. Минимум 30 с | | `autoApprove` | string[] | `[]` | Имена инструментов, которые авто-одобряются без запроса пользователя | | `enabledTools` | string[] | — | Если задано, только эти инструменты доступны агенту | | `disabledTools` | string[] | — | Инструменты, скрытые от агента | | `defaultToolsApprovalMode` | `"always-ask"` \| `"auto-approve"` | — | Режим одобрения по умолчанию для всех инструментов сервера. Записи в `autoApprove` имеют приоритет | | `auth` | объект | — | Конфигурация OAuth 2.1 для HTTP/SSE серверов (см. ниже) | ### Поля конкретных транспортов Поле `type` выбирает транспорт. Если не указано, Kodik определяет тип: конфигурация с `command` — это stdio; конфигурация с `url` и `type: "sse"` — SSE; `type: "http"` или `type: "streamableHttp"` — streamable HTTP. #### stdio — локальный процесс Запускает команду на вашей машине и общается через stdin/stdout. | Поле | Тип | Обязательно | Описание | | --------- | -------- | ----------- | --------------------------------------------------------------------- | | `command` | string | да | Исполняемый файл (например, `node`, `python`, `npx`) | | `args` | string[] | нет | Аргументы командной строки | | `env` | объект | нет | Дополнительные переменные среды, объединённые с унаследованной средой | | `cwd` | string | нет | Рабочая директория запускаемого процесса | ```jsonc { "servers": { "my-local-server": { "command": "node", "args": ["/path/to/server.js"], "env": { "API_KEY": "your_api_key", }, "timeout": 60, "autoApprove": ["read_file", "list_dir"], "disabled": false, }, }, } ``` #### sse — Server-Sent Events Подключается к удалённому серверу по HTTP с использованием SSE транспорта. Требует `type: "sse"`, когда запись сервера также имеет поле `url` (для отличия от streamable HTTP). | Поле | Тип | Обязательно | Описание | | --------- | ------------ | ----------- | ------------------------------------- | | `url` | string (URL) | да | URL SSE эндпоинта | | `headers` | объект | нет | Дополнительные HTTP заголовки запроса | ```jsonc { "servers": { "my-sse-server": { "type": "sse", "url": "https://example.com/mcp/sse", "headers": { "X-Custom-Header": "value", }, }, }, } ``` #### http — Streamable HTTP (рекомендуется для новых серверов) Современный транспорт MCP. Используйте `type: "http"` (или псевдоним `"streamableHttp"`). Оба написания принимаются и нормализуются внутри. | Поле | Тип | Обязательно | Описание | | --------- | ------------ | ----------- | ------------------------------------- | | `url` | string (URL) | да | URL streamable HTTP эндпоинта | | `headers` | объект | нет | Дополнительные HTTP заголовки запроса | ```jsonc { "servers": { "my-http-server": { "type": "http", "url": "https://example.com/mcp", }, }, } ``` ## Поведение во время работы Kodik обнаруживает настроенные MCP-серверы параллельно, поэтому один медленный сервер не блокирует весь список инструментов. Локальные stdio-серверы остаются запущенными и переиспользуются между получением списка инструментов и вызовами, а затем очищаются после простоя; при очистке завершается всё дерево процессов сервера, а не только прямой дочерний процесс. Ответы Streamable HTTP ограничены по размеру, поэтому слишком большой JSON или inline SSE завершает MCP-запрос ошибкой вместо переполнения процесса agent host. ## Одобрение инструментов По умолчанию Kodik запрашивает подтверждение перед запуском любого инструмента. Это можно изменить глобально для сервера или для конкретных инструментов. ```jsonc { "servers": { "my-server": { "command": "node", "args": ["server.js"], // Авто-одобрять все инструменты сервера без запроса: "defaultToolsApprovalMode": "auto-approve", }, }, } ``` Или добавьте конкретные имена инструментов в `autoApprove`, чтобы одобрять только их, оставив остальные в режиме always-ask: ```jsonc { "servers": { "my-server": { "command": "node", "args": ["server.js"], "autoApprove": ["read_file", "search"], }, }, } ``` Подробнее о рабочем процессе одобрения см. [Авто-одобрение](https://docs.kodik.ru/agent/auto-approve). ## Фильтрация инструментов Используйте `enabledTools`, чтобы открыть агенту только подмножество того, что предоставляет сервер, или `disabledTools`, чтобы скрыть конкретные инструменты: ```jsonc { "servers": { "big-server": { "type": "http", "url": "https://example.com/mcp", // Открыть агенту только эти два инструмента: "enabledTools": ["search", "read_document"], }, }, } ``` ## OAuth 2.1 аутентификация (HTTP/SSE серверы) Удалённые серверы могут требовать OAuth. Kodik поддерживает OAuth 2.1 с автоматическим обнаружением через Protected Resource Metadata. Блок `auth` позволяет переопределить конкретные значения, когда авто-обнаружение недоступно (например, для самостоятельно размещённых серверов без эндпоинтов `.well-known`). | Поле | Тип | Описание | | --------------------- | ------------ | --------------------------------------------------------------------- | | `disabled` | boolean | Установите `true`, чтобы полностью пропустить OAuth для этого сервера | | `clientId` | string | Предварительно зарегистрированный OAuth client ID | | `clientSecret` | string | Секрет клиента (хранится в SecretStorage при вводе через UI) | | `scopes` | string[] | Запрашиваемые OAuth области | | `authorizationServer` | string (URL) | Переопределить URL сервера авторизации | ```jsonc { "servers": { "protected-server": { "type": "http", "url": "https://api.example.com/mcp", "auth": { "clientId": "my-client-id", "scopes": ["mcp:read", "mcp:write"], "authorizationServer": "https://auth.example.com", }, }, }, } ``` Сервер, отвечающий `401`, отображается в Настройках → Серверы MCP со статусом **«Требуется аутентификация»** и кнопкой **«Войти»** рядом с переключателем. «Войти» запускает OAuth поток — браузер открывает страницу согласия сервиса, и после подтверждения сервер переходит в состояние «Подключено». Альтернативно укажите токен в `headers` сервера (например, `"Authorization": "Bearer <токен>"`) или используйте запрос **«Настроить»** у сервера плагина из маркетплейса, который объявляет токен в своей пользовательской конфигурации; заголовок с пустым токеном не отправляется, поэтому ненастроенный токен ведёт к OAuth входу. Когда агент вызывает инструмент неаутентифицированного сервера, карточка неудавшегося инструмента в чате предлагает ту же кнопку входа. Kodik подбирает OAuth-клиент в следующем порядке: явный `auth.clientId` из вашей конфигурации, встроенное приложение Kodik для данного вендора (GitHub, Slack, Google Drive, Figma), клиент, зарегистрированный при предыдущем входе, и, наконец, автоматическая динамическая регистрация клиента (DCR). Если вендор блокирует автоматическую регистрацию (как Figma), Kodik один раз запросит client ID и запомнит его. Выполненные входы сохраняются в защищённом хранилище и переиспользуются между перезапусками редактора — токены обновляются автоматически, пока вы не выйдете из сервера. ## Входные переменные Массив `inputs` определяет переменные, которые Kodik запрашивает один раз, а затем подставляет в значения конфигурации сервера. Это позволяет избежать хардкода секретов в `mcp.json`. Используйте `${input:}` в любом месте `args`, `env`, `headers` или `url`. ```jsonc { "inputs": [ { "id": "api_key", "type": "promptString", "description": "Введите ваш API ключ", "password": true, }, ], "servers": { "my-server": { "command": "node", "args": ["server.js"], "env": { "API_KEY": "${input:api_key}", }, }, }, } ``` `password: true` направляет кэшированный ответ в SecretStorage, чтобы он никогда не хранился в открытом виде. ## Управление серверами через UI Большинство операций можно выполнить без ручного редактирования файла: - **Включить/отключить**: переключите тумблер рядом с сервером во вкладке Установленные - **Перезапустить**: нажмите кнопку Перезапуск рядом с сервером или кнопку "Перезапустить Сервер" внутри панели настроек сервера - **Удалить**: нажмите красную кнопку "Удалить Сервер" в панели настроек сервера - **Тайм-аут**: используйте выпадающий список "Тайм-аут запроса" в панели настроек сервера (от 30 с до 1 ч) ## Устранение неполадок | Симптом | Вероятная причина | | ------------------------------------------ | ------------------------------------------------------------------------------------ | | Сервер не подключается | Неверная команда/путь или не установлена необходимая среда выполнения (Node, Python) | | Инструмент не виден | `disabled: true`, имя инструмента в `disabledTools` или отсутствует в `enabledTools` | | Медленные ответы | Увеличьте `timeout`; проверьте сетевую задержку для удалённых серверов | | Ошибка аутентификации на удалённом сервере | Проверьте поля `auth` или повторно запустите OAuth поток, перезапустив сервер |