Перейти до основного вмісту

Підключення MCP-клієнтів

Kandra постачається з динамічним meta-tools MCP (Model Context Protocol) сервером — одним сервером, який під час роботи виявляє кожен Документ/Довідник/Звіт/Обробку/Константу/Enum у вашій конфігурації, замість того щоб постачати окремий написаний вручну інструмент для кожного типу сутності. Підключіть до нього AI-клієнт на робочому столі, і асистент зможе переглядати, які сутності існують, описувати їхні поля, виконувати запити, створювати, оновлювати, проводити, видаляти та запускати звіти — від імені реального користувача та з його правами, так само, як якби цей користувач увійшов у систему.

Ця сторінка описує підключення трьох клієнтів: Claude Code, VS Code / GitHub Copilot Chat і Codex. Кожен приклад нижче — реальна, перевірена конфігурація, а не припущена форма.

Передумови​

  • Запущений хост Kandra з підключеною MCP-кінцевою точкою (AddKandraMcp<>() + app.MapKandraMcp() у Program.cs — див. налаштування самого рушія, якщо підключаєте це у свіжу конфігурацію; у цьому шаблоні це є з коробки).
  • API-ключ. MCP-кінцева точка приймає лише автентифікацію за API-ключем — JWT (сесія авторизованої людини) відхиляється з 403 Forbidden, і це зроблено навмисно, щоб MCP-клієнт завжди був чітко ідентифікованим нелюдським викликачем. Створіть ключ для себе в Мій профіль → API-ключі (або для іншого користувача — на сторінці редагування цього користувача); повний механізм описано в розділі «API-ключі» на сторінці Ідентифікація та автентифікація. Відкритий ключ (kdr_...) показується один раз, під час створення — скопіюйте його до закриття діалогу.
Надавайте перевагу HTTP над HTTPS

У всіх прикладах нижче використовуйте звичайний HTTP-порт (http://localhost:5219/mcp для стандартного dev-профілю запуску), а не HTTPS. Dev-слухач HTTPS використовує самопідписаний сертифікат, якому більшість MCP-клієнтів не довіряє, тож замість зрозумілої помилки ви отримаєте незрозумілу помилку TLS-рукостискання. Використовуйте справжній сертифікат, перш ніж спрямовувати клієнт на HTTPS будь-де, крім локальної розробки.

Claude Code​

claude mcp add --transport http kandra http://localhost:5219/mcp --header "X-Api-Key: kdr_..." -s local
  • --transport http — MCP-сервер є HTTP-кінцевою точкою без стану, а не stdio.
  • --header "X-Api-Key: kdr_..." — той самий заголовок, що й в усіх інших викликах API Kandra за ключем.
  • -s local/-s user — обмежте область реєстрації, щоб ключ ніколи не потрапив у закомічений .mcp.json. -s local (типово) зберігає його у ваших власних налаштуваннях проєкту поза системою контролю версій; -s user зберігає його один раз для всіх проєктів на вашій машині. Область спільного проєкту (-s project, яка записує .mcp.json у репозиторій) використовуйте лише для того, де справді немає секрету, — ніколи для цього.

Виконайте claude mcp list, щоб переконатися, що сервер зареєстровано, а потім запитайте Claude про щось, що потребує живої сутності (наприклад, «які довідники існують у цій конфігурації?»).

VS Code / GitHub Copilot Chat​

Вбудована підтримка MCP у VS Code (її використовують і агентний режим Copilot Chat, і інші чат-розширення з підтримкою MCP) читає .vscode/mcp.json. Використовуйте механізм inputs/${input:...}, щоб ключ запитувався інтерактивно й зберігався у власному сховищі секретів VS Code, а не записувався у сам файл:

{
  "servers": {
    "kandra": {
      "type": "http",
      "url": "http://localhost:5219/mcp",
      "headers": {
        "X-Api-Key": "${input:kandra-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "kandra-api-key",
      "type": "promptString",
      "description": "Kandra MCP API key",
      "password": true
    }
  ]
}

Під час першого запуску сервера VS Code запитує ключ (маскований, оскільки "password": true) і повторно використовує його протягом сесії, ніколи не записуючи в .vscode/mcp.json — цей файл безпечно комітити як є.

GitHub Copilot Chat у VS Code відповідає на питання про продажі за FEFO-собівартістю, використовуючи MCP-сервер Kandra, налаштований у .vscode/mcp.json

Codex​

Codex читає список MCP-серверів із config.toml — або з локального для проєкту .codex/config.toml, або з ~/.codex/config.toml, щоб сервер був доступний у кожному проєкті. Один нюанс, який варто окремо зазначити, бо він відрізняється від обох клієнтів вище: env_http_headers у Codex зіставляє назву заголовка з назвою змінної середовища, а не з буквальним значенням заголовка — Codex читає справжній ключ зі змінних середовища вашої оболонки під час запуску, тож ключ так само не потрапляє у файл конфігурації.

[mcp_servers.kandra]
url = "http://localhost:5219/mcp"

[mcp_servers.kandra.env_http_headers]
X-Api-Key = "KANDRA_API_KEY"

Експортуйте ключ перед запуском Codex (export KANDRA_API_KEY=kdr_... на macOS/Linux, $env:KANDRA_API_KEY = "kdr_..." у PowerShell) — Codex підставляє його в заголовок X-Api-Key у кожному MCP-виклику.

Реальна сесія: запит на звіт, а потім уточнення, якому потрібен той самий контекст:

Codex формує звіт зі списання за FEFO по тижнях, розділений на харчові продукти та ліки, через MCP-сервер Kandra Codex у тій самій сесії показує бухгалтерські проведення, створені для цих самих FEFO-продажів

Окремий користувач без прав адміністратора для агента​

Створюйте API-ключ для окремого користувача, який не є адміністратором. Адміністратори обходять усі перевірки прав, тож агент під таким користувачем читає всі регістри та весь журнал і може змінювати що завгодно. Звичайний користувач бачить лише те, що ви йому надали:

  • A|Register|View дає агенту читати всі регістри (list_registers, describe_register, query_register); O|InventoryRegister|View дає читати лише цей регістр (назва об'єкта - ім'я класу регістра). Заборона на рівні об'єкта (O|PricesRegister|View = false) ховає один регістр від дозволу на область.
  • A|Accounting|View - окреме право, потрібне для query_ledger: право на регістри не відкриває журнал, а право на журнал не відкриває регістри.
  • Регістр, який користувач не може читати, виглядає так само, як неіснуючий, а недоступні інструменти не потрапляють у список інструментів.
  • Звичайні інструменти сутностей керуються звичними правами A|Document|View, A|Dictionary|View тощо.

Те, що агент знає про регістр, береться з [Description] на класі регістра та на неочевидних полях, тож заповнюйте їх (див. скіл create-register).

Див. також​