## Что такое MCP

Model Context Protocol (MCP) — открытый протокол, который позволяет AI-агенту подключаться к внешним инструментам и источникам данных: таск-трекерам, базам данных, внутренним API, почте, любым сервисам с MCP-сервером. Вместо того чтобы каждый раз объяснять агенту контекст вручную, вы один раз подключаете нужный сервер — и его инструменты становятся доступны прямо в чате.

WorkAI не разрабатывает MCP-серверы сам, а подключается к уже существующей экосистеме — вы можете использовать любой сторонний MCP-сервер, написанный под протокол.

## Какие серверы уже есть в WorkAI

При первом запуске WorkAI добавляет в ваш список несколько готовых серверов — их не нужно искать и прописывать руками:

- **context7** — актуальная документация библиотек и фреймворков. Нужен ключ из аккаунта Context7.
- [**github**](/docs/mcp/github) — работа с репозиториями, issues и pull request'ами. Нужен персональный токен GitHub с правами на репозитории.
- **jira** — задачи и страницы Atlassian. Статичный токен не нужен: вход происходит через браузер по OAuth при первом обращении.
- **mail** — корпоративная почта по IMAP/SMTP, подходит любой провайдер. Нужны адрес почтового сервера, логин и пароль (при двухфакторной аутентификации — пароль приложения).

Все они выключены, пока вы их не включите, и требуемые ключи запрашиваются в момент включения. Список добавляется один раз: если вы удалили сервер из конфигурации, WorkAI не вернёт его обратно.

## Где включать и выключать серверы

В настройках WorkAI есть отдельный раздел с MCP-серверами. Там показан список установленных серверов, у каждого — переключатель «запустить / остановить» и текущее состояние: сколько инструментов и промптов сервер отдаёт, «запускается», «остановлен» или «ошибка». По списку работает поиск, снизу — кнопка добавления нового сервера.

Тот же раздел доступен из панели настроек агента — пункт «MCP-серверы» рядом с правилами, навыками и хуками.

![Список MCP-серверов в настройках WorkAI с переключателями и статусами подключения](./mcp-servers-settings.png)

Выключенный сервер не запускается и его инструменты агенту недоступны. Это же удобный способ временно убрать лишние инструменты, не удаляя конфигурацию.

## Как добавить свой сервер

Кнопка добавления запускает пошаговый мастер. Он спрашивает, что за сервер вы подключаете:

- **Команда (stdio)** — локальный сервер, который WorkAI запускает у вас на машине как обычный процесс.
- **HTTP** — удалённый сервер по HTTP или Server-Sent Events, вы указываете адрес.
- **Пакет** — сервер из npm, pip, NuGet или образа Docker: вы вводите имя пакета, остальное мастер заполняет сам.
- **Каталог серверов** — просмотр публичного реестра MCP прямо в WorkAI, без ручного конфига.
- **Импорт из другого приложения** — забрать серверы, уже настроенные в Cursor, Claude Desktop или Windsurf. По умолчанию такой импорт выключен, его нужно разрешить явно.

Затем мастер спрашивает имя сервера и область: **глобально** (во всех проектах) или **в этом проекте**. Серверы могут приходить и из расширений — расширение вправе объявить свой набор MCP-серверов, и они появятся в общем списке.

## Где хранится конфигурация

WorkAI понимает два формата конфига одновременно.

### Формат VS Code

Файл `mcp.json` в профиле или `.vscode/mcp.json` в проекте, с ключом `servers`. Это более развёрнутый формат: кроме команды запуска и адреса он поддерживает `inputs` (значения, которые запрашиваются у вас один раз и хранятся в защищённом хранилище), OAuth-параметры, ограничение доступа сервера к файлам и сети, режим разработки с перезапуском по изменению файлов. Именно в этот файл попадают встроенные серверы WorkAI и всё, что добавляется через мастер.

### Формат WorkAI

Второй, более простой формат — файл с ключом `mcpServers`:

- **Персональный** — `~/.workai/mcp.json`, действует во всех проектах.
- **Проектный** — `.workai/mcp.json` в корне проекта, действует только в нём.

Оба включены по умолчанию: положили файл — сервер подхватился, менять настройки не нужно.

```json title="~/.workai/mcp.json"
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

Для удалённого сервера вместо `command` указывается `url`, а заголовки — в `headers`:

```json title="~/.workai/mcp.json"
{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  }
}
```

Этот файл предназначен для любых пользовательских серверов, а не только для избранных интеграций. Важное отличие от формата VS Code — хранение секретов: подстановки здесь не работают, ключи и токены пишутся прямо в файл как обычный JSON-текст.

## Какие транспорты поддерживаются

Два: локальный сервер, запускаемый командой и общающийся через стандартный ввод-вывод, и удалённый сервер по HTTP (Streamable HTTP или Server-Sent Events). Локальному можно задать команду, аргументы, переменные окружения и файл с переменными; удалённому — адрес и заголовки.

## Как устроена авторизация

Есть три способа, и выбирает его сам сервер:

- **Ключ или токен в конфигурации** — передаётся серверу через переменные окружения (для локальных) или заголовки (для удалённых).
- **Запрос значения при подключении** — в формате VS Code поле можно объявить как ввод с подстановкой `${input:...}`. WorkAI спросит значение один раз, и, если оно помечено как пароль, сохранит его в зашифрованном виде, а не в файле конфига.
- **OAuth** — для удалённых серверов, которые его поддерживают. Вход проходит в браузере, статичный токен не нужен. Если сервер требует фиксированный client ID, его указывают в конфиге, а client secret задаётся отдельным действием прямо в редакторе `mcp.json` и хранится в системном хранилище паролей, а не в файле.

## Как агент видит инструменты сервера

Список подключённых серверов, их инструменты, ресурсы и собственные инструкции сервера подставляются агенту в системный промпт. Вызывает он их через один универсальный инструмент: указывает имя сервера, имя инструмента и аргументы. Инструкции, которые сервер сам присылает при подключении, тоже доходят до агента — поэтому серверы со своими правилами работы используются правильнее.

Выключенные серверы агент тоже видит — но помеченными как выключенные. Если вы попросите то, для чего нужен остановленный сервер, агент не станет молча пытаться, а скажет, что сервер надо включить в настройках.

Кроме инструментов, агент умеет читать ресурсы сервера — данные, которые сервер публикует по адресу, — тем же вызовом.

## Подтверждение вызова

Перед обращением к MCP-серверу WorkAI показывает диалог: какой сервер, какой инструмент и с какими аргументами. Вы разрешаете или отклоняете.

Если инструмент используется постоянно, подтверждение можно отключить — с нужной степенью широты:

- разрешить **этот инструмент** — в текущей сессии, в текущем проекте или всегда;
- разрешить **все инструменты этого сервера** — в текущей сессии, в текущем проекте или всегда.

Результат вызова показывается в чате, аргументы и ответ сервера можно развернуть.

## Что ещё умеет протокол

Инструменты — не единственная возможность MCP, и WorkAI поддерживает остальные:

- **Промпты** — готовые шаблоны запросов, которые сервер предлагает сам.
- **Ресурсы** — файлы и данные сервера; их можно и подставить в контекст вручную, и прочитать агентом.
- **Уточняющие запросы** — если серверу в процессе работы нужен ваш ответ, он показывается прямо в чате: либо формой с полями, либо ссылкой, по которой нужно перейти.
- **Границы рабочей области** — сервер может спросить, с какими папками ему разрешено работать.
- **Обращение сервера к модели** — сервер может попросить модель что-то сгенерировать; какие именно модели ему доступны, задаётся отдельно.

## Ограничение доступа локального сервера

Для серверов, которые запускаются локально командой, можно ограничить доступ к файлам и сети: перечислить разрешённые и запрещённые домены, папки для чтения и записи. Ограничение включается для конкретного сервера в конфиге формата VS Code и работает на macOS и Linux.

## Что делать, если сервер не подключается

- Посмотрите статус в списке серверов. Ошибка подключения показывается прямо на карточке, по клику открывается журнал этого сервера.
- Журнал сервера можно открыть и вручную — командой «Show Output» в меню сервера. Там видно запуск, вызовы инструментов и текст ошибок.
- Если сервер не смог запуститься по запросу агента, WorkAI откроет его журнал автоматически и сообщит причину в чате.
- В меню сервера есть перезапуск и сброс закэшированного списка инструментов — помогает, когда сервер обновился, а WorkAI показывает старый набор.
- Отдельная настройка включает подробный режим с расширенными логами для отладки серверов.

Ошибка одного сервера не ломает остальные — они продолжают работать.

## Автозапуск

По умолчанию режим автозапуска стоит на «спрашивать» — WorkAI не поднимает серверы при старте сам. Режим переключается на «запускать все при старте» или «никогда». Есть и отдельная настройка, которая поднимает все встроенные серверы, даже те, что вы не включали; по умолчанию она выключена.

Встроенный сервер, который вы включали раньше, WorkAI поднимает при следующем запуске сам. Остальные восстанавливаются, только если выбран режим «запускать все при старте».

## Чего MCP в WorkAI не делает

- **Изображения от сервера не доходят до модели.** Если MCP-сервер возвращает картинку, агент увидит только пометку, что это было изображение, и не сможет его проанализировать. Инструменты, чей результат — скриншот или диаграмма, в WorkAI пока бесполезны.
- **В файле формата WorkAI (`mcp.json` с ключом `mcpServers`) нет подстановок и защищённого хранения** — секреты там лежат открытым текстом.

## Безопасность

MCP-сервер может обращаться к внешним сервисам и выполнять код от вашего имени, поэтому при подключении стороннего сервера стоит придерживаться базовых правил:

- **Проверяйте источник** — подключайте серверы только от тех, кому доверяете. Серверы, найденные в чужих конфигурациях, WorkAI перед первым запуском покажет отдельно и спросит, каким из них вы доверяете.
- **Понимайте, к чему сервер получает доступ** — какие данные и API он затрагивает.
- **Ограничивайте права ключей** — используйте API-ключи с минимально необходимыми правами.
- **Ограничивайте самого сервера** — для локальных серверов есть запрет на лишние домены и папки.
- **Не храните секреты там, где их могут увидеть лишние люди** — если конфиг с токенами лежит в проектном `.workai/mcp.json`, убедитесь, что он не попадает в git-репозиторий.

## Дальше

Список моделей WorkAI, доступных в чате, — на странице [Модели и цены](/docs/models-and-pricing). Как MCP-инструменты сочетаются с автоматическим выбором модели — на странице [Автовыбор модели](/docs/model-router).