## Что такое MCP

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

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

## Встроенные серверы: Context7 и GitHub

WorkAI держит короткий список проверенных серверов — в каталоге MCP они собраны в группу «Рекомендуем WorkAI»:

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

Это витрина «подключить», а не автоматическая настройка. До подключения сервер существует только карточкой в каталоге — записи в вашей конфигурации нет, в списке серверов он не появляется, агент про него не знает. Подключение — одно действие: кнопка «Подключить» на карточке, поле для ключа, «Сохранить и подключить». WorkAI записывает сервер в ваш личный `~/.workai/mcp.json` вместе с введённым ключом, и дальше он ведёт себя как любой другой сервер в списке. Так же устроены Cursor, Codex и Claude Code: GitHub MCP там тоже опционален и сам в конфигурацию не прописывается.

Удалили запись из конфигурации — сервер возвращается карточкой в каталог, подключить его заново можно оттуда же.

### Почему встроенных серверов два

До 31.08.2026 их было пять: к этим двум добавлялись GitLab, Jira и почта. Три последних убраны по итогам живой проверки — каждый требовал заметных усилий на подключение и давал полурабочий результат:

- **GitLab** — сторонний пакет, требовал токен с самым широким доступом (`api`) и не работал с self-hosted-установками.
- **Почта** — три поля IMAP плюс отдельный пароль приложения при двухфакторной аутентификации.
- **Jira** — дублировал по смыслу коннектор Atlassian и вводил в заблуждение именем: один и тот же адрес отдаёт Jira, Confluence и Compass, а собственно Jira-инструментов там меньше трети.

Кому нужен любой из них — добавляет свой сервер записью в конфигурации: механика пользовательских серверов ровно для этого и предназначена. Записи, которые WorkAI успел добавить в конфигурацию до этого решения, снимаются автоматически при обновлении клиента.

Так же подключается и всё остальное — Figma, Atlassian одним входом сразу в Jira, Confluence и Compass, базы данных, внутренние API: находите нужный MCP-сервер, добавляете его в файл, и он работает наравне со встроенными.

### Figma: подключается как свой сервер, локально

Figma не входит во встроенный список — подключить её можно самостоятельно, тем же мастером, что и любой другой сервер (см. «Как добавить свой сервер» ниже).

Официальный удалённый MCP-сервер Figma (`mcp.figma.com`) принимает по OAuth только клиентов из закрытого списка — Figma MCP Catalog: там перечислены VS Code, Cursor, Claude Code, Codex и ещё несколько (сверено 23.09.2026 по developers.figma.com/docs/figma-mcp-server/remote-server-installation/). WorkAI туда пока не входит; заявка на добавление подана (workai-client#377), но решение и сроки — за Figma.

Рабочий путь до тех пор — локальный сервер, который поднимает сам Figma Desktop на своей машине по адресу `http://127.0.0.1:3845/mcp`, без OAuth и без allowlist (сверено 23.09.2026 по developers.figma.com/docs/figma-mcp-server/local-server-installation/). Чтобы им воспользоваться:

1. Откройте нужный файл в Figma Desktop, включите Dev Mode (Shift+D или переключатель на панели инструментов) и в разделе **MCP server** инспектор-панели нажмите **«Enable desktop MCP server»** — Figma подтвердит, что сервер поднят на `127.0.0.1:3845` (сверено 23.09.2026 по той же странице).
2. В WorkAI добавьте новый MCP-сервер (см. «Как добавить свой сервер» ниже), выберите тип **HTTP** и укажите адрес `http://127.0.0.1:3845/mcp`.

Сервер работает, пока Figma Desktop открыт и запущен на этой же машине; ключ или токен не нужен. Dev Mode доступен не на всех тарифах Figma — какой именно нужен seat, официальная документация не уточняет напрямую, сверяйтесь с актуальными тарифами Figma отдельно.

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

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

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

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

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

```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 считает намерением им пользоваться — тем же правилом живут Cursor и Claude Code. У режима автозапуска три значения: «спрашивать» (по умолчанию), «запускать все при старте» и «никогда». В первых двух WorkAI при старте поднимает пользовательские серверы, которые вы не выключили в списке; «никогда» отключает восстановление целиком.

Встроенные серверы живут по отдельному правилу: WorkAI поднимает тот, который вы включали раньше. Есть и отдельная настройка, которая поднимает все подключённые встроенные серверы, даже если их переключатель выключен; по умолчанию она выключена.

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

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

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

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

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

## Дальше

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