MCP

Матеріал з Planfix

MCP (Model Context Protocol) дозволяє AI-асистентам та іншим сумісним застосункам працювати з даними Planfix через стандартний протокол.

Після встановлення з'єднання клієнт отримує лише явно дозволені можливості та діє від імені співробітника, який увійшов. Стандартні права доступу Planfix зберігаються: AI-асистент не може переглядати або змінювати те, що недоступне цьому користувачу.

Доступні дії залежать від MCP-клієнта, наданих дозволів і поточної версії сервера. Наприклад, клієнт може знаходити завдання й контрагентів, читати їхні деталі та додавати коментарі, якщо для цього надано відповідні дозволи.

Вимоги

  • обліковий запис співробітника Planfix;
  • MCP-клієнт, що підтримує Streamable HTTP і OAuth.

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

Використовуйте цей URL сервера MCP: 

https://mcp.planfix.com/mcp

URL однаковий для всіх акаунтів Planfix. Не додавайте до нього назву акаунта і не надсилайте окремий заголовок акаунта. Вибір акаунта відбувається під час авторизації OAuth.

Підключення будь-якого MCP-клієнта

  1. Відкрийте налаштування сервера MCP у клієнті.
  2. Додайте новий сервер, використовуючи транспорт Streamable HTTP.
  3. Введіть назву, наприклад Planfix, і URL MCP.
  4. Збережіть налаштування та почніть автентифікацію через OAuth.
  5. У вікні браузера, що відкриється, виберіть свій акаунт Planfix. Знайти його можна за назвою, URL або електронною поштою.
  6. Перевірте назву застосунку та запитувані дозволи, після чого підтвердіть підключення.

Якщо застосунок ще не дозволено в акаунті, Planfix вкаже, що потрібне схвалення адміністратора. Адміністратор акаунта або технічний адміністратор може схвалити застосунок. Якщо адміністратор одночасно підключає застосунок, він може схвалити й підключити його в один крок.

Підключення Codex

Рекомендовано: підключення через CIMD

На planfix.com Codex автоматично обирає CIMD. Адміністратор схвалює застосунок CIMD в акаунті один раз, після чого співробітники можуть самостійно завершувати OAuth-вхід без повторного схвалення застосунку. Для цього методу не потрібно створювати застосунок вручну, надавати client_id, додавати redirect URI або зберігати секрет клієнта.

Для першого підключення адміністратор акаунта або технічний адміністратор виконує: 

codex mcp add planfix --url https://mcp.planfix.com/mcp
codex mcp login planfix

Codex відкриває браузер. Виберіть акаунт Planfix, в якому ви є адміністратором, перегляньте запитувані дозволи та виберіть Approve and connect. Застосунок CIMD потребує цього схвалення лише один раз у цьому акаунті.

Після цього кожен співробітник, якому потрібен доступ, виконує ті самі команди: 

codex mcp add planfix --url https://mcp.planfix.com/mcp
codex mcp login planfix

Співробітник входить у свій обліковий запис Planfix і підтверджує власний доступ. Адміністраторові більше не потрібно повторно схвалювати застосунок CIMD.

Альтернатива: використання застосунку, що належить акаунту

Цей метод використовуйте, коли потрібен заздалегідь визначений OAuth-клієнт, яким керує акаунт, з постійним client_id, або коли CIMD не можна використати у вашій конфігурації.

Адміністратор акаунта або технічний адміністратор створює застосунок:

  1. Відкрийте Account management → API → OAuth and MCP applications.
  2. У розділі Applications owned by this account виберіть Create application.
  3. Введіть назву, наприклад Codex.
  4. Виберіть Public client. Codex не потребує client secret.
  5. Додайте http://127.0.0.1/callback як redirect URI.
  6. Виберіть мінімальні необхідні дозволи і збережіть застосунок.
  7. Передайте згенерований client_id співробітникам, які підключатимуться.

Planfix публікує issuer і підтримує issuer-bound authorization responses, тому новий попередньо зареєстрований клієнт Codex використовує стабільну callback-адресу http://127.0.0.1/callback. Codex під час входу вставляє тимчасовий локальний порт, а Planfix приймає цей порт, якщо host і path залишаються незмінними.

Кожен користувач додає сервер, використовуючи наданий ID, і виконує вхід: 

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

Codex відобразить повний callback URL. За стандартної конфігурації це: 

OAuth callback URL: http://127.0.0.1/callback

Якщо Codex відображає іншу адресу через нестандартні налаштування callback, попросіть адміністратора додати ту точну redirect URI в налаштування застосунку.

Надання --oauth-client-id повідомляє Codex використовувати попередньо зареєстрований клієнт і пропустити CIMD та DCR. Збережена конфігурація виглядає приблизно так: 

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

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

Під час початку входу Planfix відкриє акаунт, якому належить застосунок. Перевірте дозволи та підтвердіть підключення.

Застосунок Codex та розширення IDE

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

Введіть /mcp у композері Codex, щоб переглянути активні MCP-сервери.

Щоб переглянути налаштовані сервери та їхній статус з CLI, виконайте: 

codex mcp list

Поточні елементи керування, команди та правила вибору callback для Codex описані в офіційній документації OpenAI MCP: [1].

Кілька акаунтів у Codex

Кожне з'єднання асоціюється з одним акаунтом і одним користувачем.

При використанні CIMD адміністратор повинен схвалити застосунок один раз у кожному акаунті, який ви хочете підключити. Додайте кожне підключення під іншою назвою і під час OAuth-входу виберіть потрібний акаунт. Якщо ви використовуєте застосунки, що належать акаунту, для кожного акаунта потрібен свій застосунок і client_id.

Не змінюйте URL MCP і не додавайте назву акаунта в запити. Сервер визначає акаунт за OAuth-токеном.

Вирішення проблем із підключеннями Codex

Якщо під час першого входу через CIMD потрібно схвалення адміністратора, завершіть підключення як адміністратор акаунта або технічний адміністратор і виберіть Approve and connect. Після цього співробітники зможуть самі входити.

Якщо CIMD неможливо використати і Codex запитує client_id, скористайтеся альтернативним методом із застосунком, що належить акаунту, описаним вище.

Інші MCP-клієнти без автоматичної реєстрації

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

Якщо інший клієнт вимагає заздалегідь визначений client_id, попросіть адміністратора створити публічний застосунок, що належить акаунту:

  1. Відкрийте Account management → API → OAuth and MCP applications.
  2. У Applications owned by this account створіть застосунок.
  3. Виберіть Public client.
  4. Додайте redirect URI, який показує MCP-клієнт.
  5. Виберіть мінімальні необхідні дозволи.
  6. Передайте згенерований client_id користувачу або додайте його в налаштування клієнта.

Застосунок може підключатися лише до акаунта, що його створив. Деталі див. у Додатки OAuth і MCP в акаунті.

Відключення MCP

Щоб відкликати своє з'єднання:

  1. Відкрийте свою картку користувача в Planfix.
  2. Перейдіть у Session management.
  3. Знайдіть застосунок, помічений як MCP, і видаліть сесію.
  4. Видаліть або відключіть сервер у MCP-клієнті, якщо він більше не потрібен.

Видалення сесії відкликає пов'язані OAuth-токени. Для повторного підключення знадобиться новий вхід і згода.

Адміністратор може відкликати застосунок для всього акаунта в Account management → API → OAuth and MCP applications.

Безпека

  • Підключайте лише ті застосунки, яким довіряєте.
  • Перед схваленням перевірте назву застосунку, власника, redirect URI та запитувані дозволи.
  • Надавайте мінімальні потрібні дозволи. Не давайте дозволів на зміну або видалення для сценарію, що потребує лише читання.
  • Ніколи не вставляйте access token або refresh token у чат, налаштування запиту або логи.
  • Пам'ятайте, що вміст завдань, контактів та коментарів може відправлятися до зовнішнього AI-сервісу згідно з умовами обробки даних цього сервісу.
  • Видаліть з'єднання в Session management, якщо його більше не використовують або ви його не впізнаєте.

Усунення неполадок

Повідомлення або симптом Що робити
Застосунок заблоковано політикою акаунта Адміністратор повинен схвалити конкретний застосунок або змінити політику щодо сторонніх застосунків.
Клієнт знову просить авторизацію після входу Видаліть з'єднання з клієнта та створіть його знову. Переконайтеся, що використовується точний URL MCP.
Вибрано неправильний акаунт Відкличте з'єднання та увійдіть знову, вибравши правильний акаунт. Токен не можна переключити на інший акаунт.
Операція недоступна Перевірте надані scopes та власні права доступу користувача в Planfix.

Перейти