MCP

Материал из Planfix

MCP (Model Context Protocol) позволяет AI-ассистентам и другим совместимым приложениям работать с данными ПланФикса через стандартный протокол.

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

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

Что понадобится

  • учетная запись сотрудника в ПланФиксе;
  • MCP-клиент с поддержкой транспорта Streamable HTTP и OAuth;

Адрес MCP-сервера

Используйте следующий адрес MCP-сервера: 

https://mcp.planfix.ru/mcp

URL одинаков для всех аккаунтов внутри продукта. Не добавляйте к нему имя аккаунта и не передавайте отдельный заголовок с аккаунтом — нужный аккаунт выбирается во время OAuth-авторизации.

Подключение в любом MCP-клиенте

  1. Откройте настройки MCP-серверов в клиенте.
  2. Добавьте новый сервер с транспортом Streamable HTTP.
  3. Укажите имя, например Planfix, и MCP URL.
  4. Сохраните настройки и запустите OAuth-аутентификацию.
  5. В открывшемся браузере выберите аккаунт ПланФикса. Его можно найти по имени, адресу или электронной почте.
  6. Проверьте название приложения и запрашиваемые права, затем подтвердите подключение.

Если приложение еще не разрешено в аккаунте, ПланФикс сообщит, что нужно подтверждение администратора. Администратор аккаунта или технический администратор может разрешить приложение. Если авторизуется сам администратор, он может разрешить его и подключиться одним действием.

Для DCR-подключения Codex запрос нельзя передать администратору после начала входа, поэтому заранее выберите подходящий сценарий из следующего раздела.

Подключение в Codex

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

Если вы администратор: подключение через DCR

Этот вариант доступен администратору аккаунта или техническому администратору. Во время входа он сможет одновременно разрешить автоматически зарегистрированное приложение и подключить его.

Добавьте MCP-сервер: 

codex mcp add planfix --url https://mcp.planfix.ru/mcp

Запустите OAuth-вход и явно выберите DCR как способ регистрации клиента: 

codex mcp login planfix --oauth-client-registration dcr

Codex откроет браузер. Выберите аккаунт ПланФикса, в котором вы являетесь администратором, проверьте запрашиваемые права и нажмите Разрешить и подключить.

Приложение, зарегистрированное через DCR, всегда требует явного разрешения аккаунта. Обычному сотруднику не следует начинать этот сценарий: сейчас запрос DCR-подключения нельзя отложить и передать администратору для отдельного подтверждения.

Параметр --oauth-client-registration dcr действует только для этого входа и не сохраняется в config.toml. Полученные OAuth-данные подключения Codex сохранит сам.

Если вы не администратор: подключение по client_id

Сначала попросите администратора аккаунта или технического администратора создать приложение:

  1. Откройте Управление аккаунтом → API → Приложения OAuth и MCP.
  2. В блоке Приложения этого аккаунта нажмите Создать приложение.
  3. Укажите название, например Codex.
  4. Выберите тип Публичный клиент. Client secret для Codex не требуется.
  5. Добавьте Redirect URI http://127.0.0.1/callback.
  6. Выберите минимально необходимые права и сохраните приложение.
  7. Передайте пользователю полученный client_id.

ПланФикс публикует issuer и поддерживает привязку ответа авторизации к нему, поэтому новый pre-registered клиент Codex использует стабильный callback http://127.0.0.1/callback. Во время входа Codex добавляет временный loopback-порт; ПланФикс принимает такой порт при неизменных хосте и пути.

Пользователь добавляет сервер, подставив выданный идентификатор: 

codex mcp add planfix --url https://mcp.planfix.ru/mcp --oauth-client-id CLIENT_ID

Codex покажет полный callback URL. В стандартной конфигурации он выглядит так: 

OAuth callback URL: http://127.0.0.1/callback

Если показан другой адрес из-за пользовательских настроек Codex, попросите администратора добавить в приложение именно этот Redirect URI.

Затем выполните: 

codex mcp login planfix

Наличие --oauth-client-id означает, что Codex использует предварительно зарегистрированный клиент и не запускает CIMD или DCR. Настройки сохраняются примерно в таком виде: 

[mcp_servers.planfix]
url = "https://mcp.planfix.ru/mcp"

[mcp_servers.planfix.oauth]
client_id = "CLIENT_ID"
callback_url = "http://127.0.0.1/callback"

Приложение Codex и расширение для IDE

Приложение Codex, Codex CLI и расширение для IDE используют общую конфигурацию MCP на одном компьютере. После первого подключения через CLI перезапустите приложение или расширение. Сервер появится в Settings → MCP servers. Если рядом с ним отображается Authenticate, нажмите эту кнопку и завершите вход.

Проверить активные MCP-серверы можно командой /mcp в поле ввода Codex.

Список и состояние подключений можно посмотреть командой: 

codex mcp list

Актуальные элементы интерфейса, команды и правила выбора callback описаны в официальной справке OpenAI по MCP.

Если другой MCP-клиент не умеет регистрироваться автоматически

Современный MCP-клиент может зарегистрироваться автоматически через CIMD или DCR. Такая регистрация не дает доступ к аккаунту сама по себе: правила аккаунта и подтверждение администратора сохраняются.

Если клиент требует заранее заданный client_id, попросите администратора создать публичное приложение аккаунта:

  1. Откройте Управление аккаунтом → API → Приложения OAuth и MCP.
  2. В блоке Приложения этого аккаунта создайте приложение.
  3. Выберите тип Публичный клиент.
  4. Добавьте Redirect URI, который показывает MCP-клиент.
  5. Выберите минимально необходимые права.
  6. Передайте полученный client_id пользователю или внесите его в настройки клиента.

Такое приложение сможет подключаться только к создавшему его аккаунту. Подробности — в статье Приложения OAuth и MCP в аккаунте.

Несколько аккаунтов

Каждое подключение связано с одним аккаунтом и одним пользователем.

  • При подключении через DCR добавьте еще один MCP-сервер под другим именем и во время входа выберите другой аккаунт, в котором у вас есть права администратора.
  • Приложение аккаунта и его client_id действуют только в создавшем его аккаунте. Для другого аккаунта его администратор должен создать отдельное публичное приложение; добавьте его в Codex под другим именем с новым client_id.

Не изменяйте MCP URL и не добавляйте к запросам имя аккаунта. Сервер определяет аккаунт по выданному OAuth-токену.

Как отключить MCP

Чтобы отозвать свое подключение:

  1. Откройте свою карточку пользователя в ПланФиксе.
  2. Перейдите в раздел Управление сессиями.
  3. Найдите приложение с пометкой MCP и удалите сессию.
  4. Удалите или отключите сервер в MCP-клиенте, если он больше не нужен.

Удаление сессии отзывает связанные OAuth-токены. Повторное подключение потребует нового входа и согласия.

Администратор может отозвать приложение для всего аккаунта в разделе Управление аккаунтом → API → Приложения OAuth и MCP.

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

  • Подключайте только приложения, которым доверяете.
  • Перед подтверждением проверяйте название приложения, владельца, Redirect URI и список запрашиваемых прав.
  • Выдавайте минимально необходимые права. Для сценария только чтения не разрешайте изменение или удаление данных.
  • Не вставляйте access token или refresh token в чат, настройки запроса или логи.
  • Учитывайте, что содержание задач, контактов и комментариев может передаваться внешнему AI-сервису в соответствии с его условиями обработки данных.
  • Если подключение больше не используется или выглядит незнакомым, удалите его в разделе Управление сессиями.

Возможные проблемы

Если при DCR-входе требуется разрешение администратора, войдите как администратор аккаунта или технический администратор и нажмите Разрешить и подключить. Обычный сотрудник не может передать начатый DCR-запрос на отдельное подтверждение.

Сообщение или симптом Что сделать
Приложение запрещено политикой аккаунта Администратор должен разрешить конкретное приложение или изменить политику сторонних приложений.
После входа клиент снова просит авторизацию Удалите подключение в клиенте и создайте его заново. Проверьте, что используется точный MCP URL нужного продукта.
Выбран не тот аккаунт Отзовите подключение и повторите вход, выбрав нужный аккаунт. Один токен нельзя переключить на другой аккаунт.
Клиент просит client_id Попросите администратора создать публичное приложение аккаунта и добавьте MCP-сервер с параметром --oauth-client-id.
Операция недоступна Проверьте выданные scope и права самого пользователя в ПланФиксе.

Перейти