# mcp

> Команда stackql mcp запускає StackQL як сервер Model Context Protocol для агентів ШІ: режими розгортання й безпеки, повторне завантаження облікових даних і журнал аудиту.

Source: https://stackql.io/uk/command-line-usage/mcp

Команда для запуску StackQL як сервера Model Context Protocol (MCP), що дає змогу агентам і асистентам ШІ взаємодіяти з хмарною інфраструктурою за допомогою можливостей StackQL для виконання запитів.

:::info[Що таке MCP?]

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - це відкритий протокол, який стандартизує взаємодію застосунків ШІ із зовнішніми джерелами даних та інструментами.  Запустивши StackQL як сервер MCP, ви можете дати змогу агентам ШІ (Claude, Cursor, Continue, власним агентам тощо) виконувати запити до хмарної інфраструктури кількох провайдерів і керувати нею за допомогою природної мови.

:::

* * *

### Синтаксис

`stackql mcp [flags]` для автономного сервера MCP.

`stackql srv [flags]` для запуску сервера MCP разом із сервером мережевого протоколу PostgreSQL в одному процесі.

* * *

### Режими розгортання

Сервер MCP StackQL можна розгорнути в трьох різних конфігураціях відповідно до різних архітектурних вимог.  Приклади нижче явно вмикають обслуговування без автентифікації за допомогою `"allow_unauthenticated": true`, що підходить для локальної розробки; для сервера, до якого може звертатися інший процес або хост, натомість налаштуйте токен bearer (див. [Автентифікація клієнтів HTTP](#http-client-authentication)).

#### 1. Автономний сервер MCP

Запустіть StackQL як виділений сервер MCP на вказаному порту.

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'
```

**Сценарій використання:** коли вам потрібен лише доступ за протоколом MCP і не потрібна сумісність із мережевим протоколом PostgreSQL.

#### 2. MCP + сервер PostgreSQL (у пам'яті)

Запустіть сервери MCP і PostgreSQL одночасно із взаємодією між ними в пам'яті.

```bash
stackql srv \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}' \
  --pgsrv.port 5665
```

**Сценарій використання:** коли вам потрібен і доступ за протоколом MCP для агентів ШІ, і мережевий протокол PostgreSQL для традиційних клієнтів баз даних, з максимальною продуктивністю завдяки взаємодії в пам'яті.

#### 3. MCP + сервер PostgreSQL (зворотний проксі)

Запустіть обидва сервери із взаємодією через TCP, що підтримує розподілені розгортання та шифрування TLS.

```bash
stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9004", "allow_unauthenticated": true}, "backend": {"dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"}}' \
  --pgsrv.port 5446
```

**Із шифруванням TLS:**

```bash
stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{"server": {"tls_cert_file": "/path/to/server_cert.pem", "tls_key_file": "/path/to/server_key.pem", "transport": "http", "address": "127.0.0.1:9004", "auth_token_env_var": "STACKQL_MCP_TOKEN"}, "backend": {"dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"}}' \
  --pgsrv.port 5446
```

TLS шифрує транспорт, але не автентифікує клієнта, тому цей приклад також вимагає токен bearer, що зберігається в `STACKQL_MCP_TOKEN`.

**Сценарій використання:** коли потрібно розділити навантаження MCP і PostgreSQL між різними процесами або хостами чи коли потрібне шифрування TLS для кінцевої точки MCP.

* * *

### Параметри конфігурації

#### Тип сервера MCP

| Тип | Опис |
|--|--|
|`http`|Режим прямого сервера HTTP - запити MCP обробляє рушій StackQL у тому самому процесі.|
|`reverse_proxy`|Режим зворотного проксі - запити MCP надсилаються базовому серверу PostgreSQL через налаштований DSN.  Використовується з `stackql srv`.|
|`stdio`|Транспорт стандартного вводу/виводу - сервер читає запити з `stdin` і записує відповіді в `stdout`.  Використовується клієнтами MCP, вбудованими в редактори (Claude Desktop, Cursor тощо).|

#### Формат журналу MCP

Прапорець `--mcp.log.format` вибирає кодування журналу аудиту: `jsonl` (за замовчуванням) або `otel` (записи журналу OpenTelemetry у форматі OTLP/JSON).  Він перевизначає `server.audit.format` в об'єкті конфігурації.  Див. [Формат журналу](#log-format).

#### Версія протоколу MCP

Прапорець `--mcp.protocol.version` встановлює найновішу ревізію протоколу, яку оголошує сервер: `auto` (за замовчуванням, усі підтримувані ревізії), `2026-07-28` (лише без сеансу) або старішу ревізію, наприклад `2025-11-25` (ця ревізія та старіші).  Він перевизначає `server.protocol_version` в об'єкті конфігурації.  Див. [Закріплення ревізії](#pinning-the-revision).

#### Об'єкт конфігурації MCP

Прапорець `--mcp.config` приймає об'єкт JSON такої структури.

##### Конфігурація сервера

| Поле | Опис | Обов'язковий |
|--|--|--|
|`server.transport`|Транспортний протокол - `http` або `stdio`.|Так|
|`server.address`|Адреса й порт для прив'язки сервера MCP (наприклад, `127.0.0.1:9912`).  Лише для транспорту HTTP.|Для `http`|
|`server.tls_cert_file`|Шлях до файлу сертифіката TLS для HTTPS.|Ні|
|`server.tls_key_file`|Шлях до файлу закритого ключа TLS для HTTPS.|Ні|
|`server.auth_token_env_var`|Ім'я змінної середовища, що містить попередньо наданий спільний токен bearer.  Якщо поле встановлено, кожен запит HTTP має містити `Authorization: Bearer <token>`; сервер відмовляється запускатися, якщо змінну не встановлено або вона порожня.  Див. [Автентифікація клієнтів HTTP](#http-client-authentication).|Це поле або `allow_unauthenticated`, для `http`|
|`server.allow_unauthenticated`|Явне ввімкнення обслуговування транспорту HTTP без автентифікації клієнтів.  За замовчуванням: `false`.|Це поле або `auth_token_env_var`, для `http`|
|`server.mode`|Контракт безпеки, який контролює операції змінення даних і операції життєвого циклу.  Одне зі значень `read_only`, `safe` (за замовчуванням), `delete_safe`, `full_access`.  Див. [Режими сервера](#server-modes).|Ні|
|`server.read_only`|**Старий** логічний псевдонім для `mode: read_only`.  Якщо встановлено обидва поля, перевагу має `mode`.|Ні|
|`server.stateless`|Обслуговування Streamable HTTP без сеансів (без `Mcp-Session-Id`); саме так через HTTP обслуговується ревізія протоколу `2026-07-28`.  За замовчуванням: `false`.  Ігнорується для `stdio`.  Див. [Підтримка ревізій протоколу](#protocol-revision-support).|Ні|
|`server.protocol_version`|Найновіша ревізія протоколу, що оголошується: `auto` (за замовчуванням), `2026-07-28` або старіша ревізія, наприклад `2025-11-25`.  `2026-07-28` передбачає `stateless` для Streamable HTTP.  Див. [Закріплення ревізії](#pinning-the-revision).|Ні|
|`server.audit`|Конфігурація підсистеми аудиту, зокрема `audit.format` (`jsonl` або `otel`).  Див. [Журнал аудиту](#audit-log).|Ні|

##### Конфігурація бекенду (лише режим зворотного проксі)

| Поле | Опис | Обов'язковий |
|--|--|--|
|`backend.dsn`|Рядок підключення PostgreSQL до сервера StackQL, що слугує бекендом.|Так (для `reverse_proxy`)|

:::info

DSN бекенду має містити параметр `default_query_exec_mode=simple_protocol` для оптимальної сумісності.

:::

##### Списки дозволених

| Поле | Опис |
|--|--|
|`enabled_tools`|Масив імен інструментів, які серверу дозволено публікувати.  Якщо поле пропущено або порожнє, реєструються всі вбудовані інструменти.  Використовується, щоб надати доступ лише до вузької підмножини (наприклад, сервер інвентаризації лише для читання).|
|`enabled_prompts`|Масив імен промптів.  Та сама семантика, що й для `enabled_tools`, але для набору промптів.|

Приклад - сервер, який публікує лише `server_info` і `list_providers`:

```json
{
  "server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true},
  "enabled_tools": ["server_info", "list_providers"]
}
```

* * *

### Підтримка ревізій протоколу

Ревізія протоколу `2026-07-28`, `server.stateless` і формат журналу аудиту `otel` доступні в StackQL `v0.11.660` і новіших версіях.  `server.protocol_version` і прапорець `--mcp.protocol.version` доступні в StackQL `v0.12.732` і новіших версіях.

Сервер працює з усіма ревізіями Model Context Protocol, які підтримує [Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk), і узгоджує ревізію окремо з кожним клієнтом, тож парк різних клієнтів працює з одним сервером.

| Ревізія | Життєвий цикл | Запит на схвалення (`safe` / `delete_safe`) |
|--|--|--|
|`2026-07-28` (оголошується)|Без рукостискання: `server/discover`, після чого кожен запит містить `io.modelcontextprotocol/protocolVersion` і `io.modelcontextprotocol/clientCapabilities` у `_meta` (а також заголовки `Mcp-Protocol-Version`, `Mcp-Method` і `Mcp-Name` для HTTP).|Результат `input_required`; клієнт повторює виклик з `inputResponses` (SEP-2322).|
|`2025-11-25`, `2025-06-18`|Рукостискання `initialize` / `notifications/initialized`.|Запит `elicitation/create`, ініційований сервером.|
|`2025-03-26`, `2024-11-05`|Як вище.|Як вище.|

**stdio** обслуговує всі ревізії в одному процесі: перший запит клієнта ревізії `2026-07-28` обслуговується без рукостискання, а `initialize` старішого клієнта все одно працює.  Для Claude Desktop, засобів запуску npm / PyPI чи образу Docker нічого налаштовувати не потрібно.

**Streamable HTTP** за замовчуванням використовує модель зі збереженням стану з окремим сеансом для кожного клієнта (`Mcp-Session-Id`), яку SDK обслуговує для ревізій до `2025-11-25` включно.  На запит ревізії `2026-07-28` сервер відповідає помилкою JSON-RPC `-32022` (непідтримувана версія протоколу; у випусках до `v0.12.718` включно - звичайний HTTP 400), поле `data.supported` якої перелічує ревізії з рукостисканням, і `server/discover` оголошує те саме, тож клієнт узгоджує нижчу ревізію, а наявні інтеграції HTTP зберігають свої сеанси й запити на схвалення без змін.  Встановіть `server.stateless` (або закріпіть ревізію `2026-07-28`, [нижче](#pinning-the-revision)), щоб обслуговувати `2026-07-28` нативно через HTTP:

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "stateless": true}}'
```

Сервер без сеансу не видає `Mcp-Session-Id`, відповідає на `GET` і `DELETE` кодом 405 (немає сеансу, який потрібно завершувати), зберігає `tools/list`, `prompts/list` і `resources/list` незмінними незалежно від з'єднання і виконує цикл схвалення через `input_required`.  Він і далі приймає `initialize` старішого клієнта й обслуговує для нього операції читання, але не може зберегти можливість elicitation, яку цей клієнт оголосив під час ініціалізації (кожен запит отримує тимчасовий сеанс), тому старіші клієнти на сервері без сеансу не можуть схвалювати операції запису, що потребують схвалення.  Вибирайте `stateless` для хостів поточної ревізії, а значення за замовчуванням - для парку, у якому ще є старіші клієнти.

Сервер не зберігає стан між викликами: режим, аудит і облікові дані провайдерів - це конфігурація на рівні процесу, тож нічого не потрібно переносити за явні дескриптори.

#### Закріплення ревізії

За замовчуванням сервер оголошує всі підтримувані ревізії й узгоджує ревізію окремо з кожним клієнтом.  Прапорець `--mcp.protocol.version` або `server.protocol_version` в об'єкті конфігурації (прапорець має перевагу) встановлює найновішу ревізію, що оголошується:

```bash
# sessionless only; stateless Streamable HTTP is implied
stackql mcp \
  --mcp.server.type=http \
  --mcp.protocol.version=2026-07-28 \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'

# handshake lifecycle only
stackql mcp --mcp.server.type=stdio --mcp.protocol.version=2025-11-25
```

| Значення | Оголошується | Ефект |
|--|--|--|
|`auto` (за замовчуванням) або відсутнє|Усі підтримувані ревізії.|Узгодження, як описано вище: найвища ревізія, яку підтримують обидві сторони.|
|`2026-07-28`|Лише `2026-07-28`.|Лише без сеансу, і для Streamable HTTP передбачається `stateless`.  На `initialize` старішого клієнта сервер відповідає `2025-11-25`, що є сигналом для цього клієнта від'єднатися, а не сприйняти відповідь як новий життєвий цикл.|
|`2025-11-25` (або будь-яка старіша ревізія)|Ця ревізія та всі попередні.|Лише життєвий цикл із рукостисканням: запит ревізії `2026-07-28` отримує помилку JSON-RPC `-32022`, поле `data.supported` якої перелічує оголошені ревізії, тож клієнт може повторно узгодити ревізію.  Старіші клієнти з рукостисканням зберігають свою ревізію.|

Будь-яке інше значення не проходить перевірку конфігурації під час запуску, і помилка називає допустимі значення.

#### Обмеження транспорту

Тіло запиту Streamable HTTP обмежено 4 MiB (понад це - HTTP 413), JSON із вкладеністю понад 1000 рівнів відхиляється до синтаксичного аналізу, а один кадр `stdio` обмежено 8 MiB.  Жодне з цих обмежень не налаштовується; усі вони значно перевищують розмір будь-якої інструкції SQL, яку приймає сервер.

* * *

### (Повторне) завантаження облікових даних (`--env.file` + `reload_credentials`)

:::note

`--env.file` та інструмент `reload_credentials` доступні у випусках StackQL після `v0.10.542`.

:::

Блок середовища процесу фіксується під час запуску процесу.  Це створює дві проблеми для серверів MCP:

- Сервер MCP із транспортом `stdio`, запущений настільним клієнтом (Claude Desktop, Cursor тощо) без змінних середовища з обліковими даними, ніколи їх не побачить - клієнт передає дочірньому процесу власне середовище.
- Короткострокові облікові дані після ротації ніколи не потрапляють у сеанс сервера, що працює тривалий час.

Прапорець `--env.file` вирішує обидві проблеми, вказуючи файл у стилі dotenv, що слугує змінюваним сховищем облікових даних:

```bash
stackql mcp --mcp.server.type=stdio --env.file /path/to/stackql-credentials.env
```

#### Семантика завантаження

Файл завантажується в середовище процесу під час запуску для кожної точки входу (`exec`, `shell`, `srv`, `registry`, `mcp`):

- Якщо прапорець порожній або не встановлений, нічого не відбувається - облікові дані визначаються відкладено із середовища процесу в момент запиту, точно як раніше.
- Відсутній файл за вказаним шляхом допускається й нічого не змінює (файл може бути створено пізніше).
- Неправильно сформований або недоступний для читання файл спричиняє критичну помилку під час запуску.
- Встановлюються лише ключі з непорожніми значеннями; наявні змінні середовища процесу **перезаписуються** (файл є джерелом істини); значення жодної змінної ніколи не скасовується.
- Прапорець працює лише в командному рядку - він не завантажується з `.stackqlrc`.

Формат файлу: одна пара `KEY=VALUE` на рядок.  Допускаються коментарі `#`, порожні рядки, необов'язковий префікс `export `, необов'язкові одинарні або подвійні лапки навколо значення та закінчення рядків CRLF:

```bash
# stackql-credentials.env
export OKTA_SECRET_KEY="00abc...xyz"
STACKQL_GITHUB_USERNAME=myuser
STACKQL_GITHUB_PASSWORD='ghp_mytoken'
```

#### `reload_credentials`

Інструмент [`reload_credentials`](/mcp/reload_credentials) повторно завантажує файл `--env.file` у середовище процесу посеред сеансу, а потім звітує про стан визначення облікових даних для кожного провайдера.  Секретні значення ніколи не повертаються, не записуються в журнал і не потрапляють до аудиту - лише імена та стани.  Без налаштованого `--env.file` інструмент працює лише як перевірка стану.

Коли запит не вдається через помилку визначення облікових даних, помилка MCP містить підказку, яка спрямовує агента викликати `reload_credentials` і повторити спробу, тож агентні клієнти відновлюються самостійно: запишіть облікові дані у файл, попросіть агента виконати повторне завантаження, і запит, що не вдався, успішно виконається під час повторної спроби - без перезапуску сервера.

`reload_credentials` не підтримується в режимі бекенду `reverse_proxy` - запити виконуються в процесі віддаленого сервера stackql, тому інструмент повертає помилку, яка спрямовує користувача виконати повторне завантаження на базовому сервері.

#### Windows і Claude Desktop

`setx` записує в реєстр, а не в запущені процеси, а Claude Desktop передає дочірнім процесам MCP власне (неактуальне) середовище - тому зміни облікових даних зазвичай вимагають повного перезапуску Claude Desktop.  З `--env.file` файл облікових даних можна створити або ротувати будь-коли, і `reload_credentials` підхопить його без жодного перезапуску.  Приклад конфігурації див. на сторінці [Використання StackQL із Claude Desktop](/getting-started/claude-desktop).

* * *

### Автентифікація клієнтів HTTP

:::note

`server.auth_token_env_var` і `server.allow_unauthenticated` доступні в StackQL `v0.12.742` і новіших версіях.

:::

Транспорт HTTP вимагає автентифікації клієнтів.  `server.auth_token_env_var` містить ім'я змінної середовища з попередньо наданим спільним токеном bearer; кожен запит має містити `Authorization: Bearer <token>`, інакше сервер відповідає `401`.  Токен зчитується із середовища, тому ніколи не з'являється в `--mcp.config` чи аргументах процесу.

```bash
export STACKQL_MCP_TOKEN="$(openssl rand -hex 32)"

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "auth_token_env_var": "STACKQL_MCP_TOKEN"}}'
```

:::info[Потрібна автентифікація сервера]

Обслуговування без токена потребує явного ввімкнення: встановіть `"allow_unauthenticated": true` у `server`.  Якщо немає жодного з цих ключів, сервер завершує роботу під час запуску з повідомленням, у якому названо обидва; він також завершує роботу, якщо змінну з токеном не встановлено або вона порожня.  Починаючи з випуску `v0.12.742`, під час використання транспорту `http` потрібно додати до `server` або `auth_token_env_var`, або `"allow_unauthenticated": true`.

:::

TLS (`tls_cert_file` / `tls_key_file`) шифрує транспорт, але не автентифікує клієнта; поєднуйте його з токеном для будь-якого прослуховувача за межами loopback.  Запити браузера з іншого джерела (невідповідний `Origin` або міжсайтовий `Sec-Fetch-Site`) відхиляються з кодом `403` незалежно від автентифікації.  Клієнт `stackql_mcp_client`, що входить до комплекту, не надсилає заголовок `Authorization`, тому сервер, з яким він працює, має явно ввімкнути обслуговування без автентифікації.

Починаючи з `v1.0`, запуск сервера з [`--access.config`](/command-line-usage/access-management) замінює перевірку спільного токена автентифікацією кожної сторони, що викликає: кожен запит HTTPS перевіряється за налаштованою схемою JWT, статичного токена bearer або взаємного TLS і авторизується за правилами політики.  У цьому разі TLS сервера обов'язковий, автентифікація `local_os` через HTTP відхиляється, а для запиту без облікових даних токен із середовища сервера ніколи не використовується як резервний варіант.  Керування доступом недоступне з типом сервера `reverse_proxy`.

* * *

### Режими сервера

`server.mode` вибирає один із чотирьох контрактів безпеки.  Усі чотири дозволяють `SELECT` і читання метаданих; вони відрізняються тим, як обробляють операції змінення даних і операції життєвого циклу.

| Режим | `SELECT` / метадані | `INSERT` / `UPDATE` / `REPLACE` | `DELETE` | `EXEC` (життєвий цикл) |
|--|--|--|--|--|
|`read_only`|дозволено|відхилено|відхилено|відхилено|
|`safe` (за замовчуванням)|дозволено|потрібне схвалення|потрібне схвалення|потрібне схвалення|
|`delete_safe`|дозволено|дозволено|потрібне схвалення|потрібне схвалення|
|`full_access`|дозволено|дозволено|дозволено|дозволено|

**Відхилено** означає, що клієнт одразу отримує помилку.

**Потрібне схвалення** означає процес elicitation MCP, форма якого залежить від узгодженої [ревізії протоколу](#protocol-revision-support):

- Якщо клієнт оголосив можливість elicitation (під час ініціалізації або в можливостях клієнта в `_meta` кожного запиту для `2026-07-28`), сервер просить користувача схвалити дію за допомогою короткого повідомлення (ім'я інструмента, клас запиту, SQL).  У `2026-07-28` запит на схвалення повертається як результат `input_required`, що містить запит вхідних даних `elicitation/create` з ідентифікатором `stackql_approval`, і клієнт повторює виклик із відповіддю в `inputResponses`; у попередніх ревізіях сервер сам надсилає запит `elicitation/create` посеред виклику.  Користувач приймає, відхиляє або скасовує дію.
- Якщо клієнт **не** оголосив elicitation, інструмент відхиляється з повідомленням, яке пояснює цю невідповідність і спрямовує оператора до режиму `full_access`.

Схвалення надає клієнт, тому воно захищає від дій агента без відома його користувача, а не від недовіреної сторони, що викликає.  Поєднуйте транспорт HTTP з [автентифікацією клієнтів](#http-client-authentication), якщо сторонам, що викликають, не можна довіряти.

Режим глобальний для всього сервера.  Перевизначення для окремих інструментів немає.

Починаючи з `v1.0`, [`run_select_query`](/mcp/run_select_query) відхиляє `INSERT`, `UPDATE`, `REPLACE`, `DELETE` і `EXEC` в усіх режимах, зокрема в `full_access`; помилка називає `run_mutation_query` або `run_lifecycle_operation`.  Кожен інструмент також має `title` і чотири поведінкові підказки MCP як явні логічні значення (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), отримані з тієї самої класифікації, яку застосовує контроль політик.  `openWorldHint` має значення `true` для `list_registry`, `pull_provider`, `run_select_query`, `run_mutation_query` і `run_lifecycle_operation`, які звертаються до кінцевих точок реєстру або провайдерів, і `false` для інструментів, які читають лише локальний стан.  Підказки мають рекомендаційний характер для інтерфейсу клієнта; примусове застосування правил залишається за контролем політик.

:::info[Контроль корисного навантаження]

Починаючи з випуску `v0.12.742`, корисне навантаження з кількома інструкціями контролюється за його найпривілейованішою інструкцією в усіх режимах, тому `SELECT 1; DELETE ...` розглядається як `DELETE`, а запис аудиту містить `query_class` `mutation_delete`.  `validate_select_query` приймає рівно одну інструкцію.

:::

#### Зміна поведінки режиму за замовчуванням

Попередні випуски забезпечували безпеку лише за допомогою одного прапорця `read_only: true/false`, значенням за замовчуванням якого було "без обмежень".  Поточне значення за замовчуванням (`mode: safe`) робить так, що операції змінення даних одразу після встановлення потребують схвалення користувача.  Оператори, які використовують клієнт MCP з підтримкою elicitation (Claude Desktop, Cursor, Continue тощо), бачитимуть один запит на схвалення для кожної операції змінення даних.  Оператори, які запускають автоматизацію або `stackql_mcp_client` з комплекту (який не оголошує elicitation), мають явно вибрати менш обмежувальний режим: `mode: delete_safe`, щоб виконувати `INSERT`, `UPDATE` і `REPLACE`, або `mode: full_access`, щоб також виконувати `DELETE` та операції життєвого циклу.

Старий ключ JSON / YAML `read_only: true` досі приймається для зворотної сумісності й вважається еквівалентом `mode: read_only`.

#### Приклади

```bash
# Read-only: SELECTs proceed; mutations and lifecycle refused immediately.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "read_only"}}'

# Delete-safe: INSERT/UPDATE/REPLACE proceed; DELETE and EXEC need approval.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "delete_safe"}}'

# Full access: everything proceeds without prompting.  Use only with trusted
# clients and operators.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "full_access"}}'
```

* * *

### Журнал аудиту

Кожен виклик інструмента створює один запис у налаштованому місці призначення аудиту, за замовчуванням у форматі JSONL або як записи журналу OpenTelemetry (див. [Формат журналу](#log-format)).  Аудит **увімкнено за замовчуванням**.  Аудит відповідає на питання "що зробив агент", а не "що побачив агент" - рядки результатів інструкцій `SELECT` навмисно не записуються в жодному з форматів.

#### Що записується

| Поле | Опис |
|--|--|
|`timestamp`|Фактичний час початку виклику (RFC3339).|
|`tool`|Ім'я інструмента (наприклад, `run_select_query`).|
|`mode`|Режим сервера, чинний на момент виклику.|
|`decision`|`allow` / `refuse_immediate` / `needs_approval_accepted` / `needs_approval_declined` / `needs_approval_cancelled` / `needs_approval_unavailable`.|
|`query_class`|`select` / `mutation_create` / `mutation_delete` / `lifecycle` / `unknown`.  Для корисного навантаження з кількома інструкціями - клас найпривілейованішої з них.|
|`sql`|Рядок SQL для інструментів запитів (`run_select_query`, `run_mutation_query`, `run_lifecycle_operation`, `validate_select_query`).|
|`args`|Поля ієрархії для інструментів метаданих (`list_*`, `describe_method`); SQL + `row_limit` для інструментів запитів.|
|`duration_ms`|Фактична тривалість роботи контролю + обробника.|
|`error`|Повідомлення про помилку, якщо інструмент завершився з помилкою або його було відхилено.|

Рядки результатів інструкцій `SELECT` навмисно виключено - вони можуть бути дуже великими й містити конфіденційні дані.

#### Файлове місце призначення

Наразі доступне лише місце призначення `file`.  Один об'єкт JSON на рядок, fsync після кожного запису, ротація в стилі lumberjack за розміром / віком / кількістю резервних копій.

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "allow_unauthenticated": true,
      "audit": {
        "file": {
          "path": "/var/log/stackql-mcp.log",
          "max_size_mb": 100,
          "max_backups": 5,
          "max_age_days": 30
        }
      }
    }
  }'
```

Розташування можна вказати двома способами:

- `audit.file.path` - повний шлях до файлу (абсолютний або відносно поточного каталогу).
- `audit.file.dir` - каталог; місце призначення вибирає в ньому ім'я файлу `stackql_mcp_server_<RFC3339-utc-second>.log`.

Якщо жодне з них не встановлено в `mcp.config`, сервер MCP за замовчуванням використовує поточний каталог як `dir`, тож для наявних операторів поведінка залишається такою самою, як раніше.  Базовий універсальний пакет місць призначення сам відмовляється мовчки вибирати каталог - рішення про те, "куди потрапляють журнали", завжди ухвалює сторона, що викликає.

Визначений абсолютний шлях виводиться в stderr під час запуску як `sink file: /path/to/file.log`.

#### Формат журналу

Потік аудиту має два кодування, які записуються в те саме файлове місце призначення:

```bash
stackql mcp --mcp.server.type=stdio --mcp.log.format=jsonl   # default, unchanged
stackql mcp --mcp.server.type=stdio --mcp.log.format=otel    # OTLP/JSON log records
```

Прапорець перевизначає `server.audit.format` у `mcp.config` (`"audit": {"format": "otel"}`).  `jsonl` побайтово сумісний із записами, описаними вище.  `otel` записує один об'єкт OTLP/JSON `LogsData` на рядок у формі, яку приймач `otlp_json_file` в OpenTelemetry Collector отримує без змін (перевірено з otelcol-contrib 0.160.0), тож потік потрапляє в будь-який конвеєр OTLP без процесора перетворень:

```yaml
receivers:
  otlp_json_file:
    include: [/var/log/stackql-mcp.log]
exporters:
  debug: {}
service:
  pipelines:
    logs:
      receivers: [otlp_json_file]
      exporters: [debug]
```

Кожен виклик інструмента створює один запис журналу; виклик, що пройшов через контроль схвалення, створює другий запис для рішення elicitation.  Записи одного виклику мають спільні `gen_ai.tool.call.id` та ідентифікатор трасування.  Значення W3C `traceparent`, яке сторона, що викликає, передає в `params._meta`, враховується; інакше для кожного сеансу MCP генерується один ідентифікатор трасування, щоб записи сеансу агента можна було зіставити.

Набір атрибутів, що виводиться, є версіонованим інтерфейсом: область інструментування - `github.com/stackql/stackql/pkg/mcp_server/audit` версії `1.0.0`, а `schemaUrl` закріплює стабільні конвенції на `https://opentelemetry.io/schemas/1.44.0`.  Атрибути `gen_ai.*` і `mcp.*` відповідають семантичним конвенціям [GenAI](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span) і [MCP](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md), які мають статус Development; версія області збільшується, коли набір змінюється.

| Атрибут | Запис | Значення |
|--|--|--|
|`service.name`, `service.version`|ресурс|`stackql`, версія StackQL|
|`gen_ai.operation.name`|виклик інструмента|`execute_tool`|
|`mcp.method.name`|обидва|`tools/call` у записі виклику інструмента, `elicitation/create` у записі рішення|
|`gen_ai.tool.name`|обидва|Ім'я інструмента|
|`gen_ai.tool.call.id`|обидва|Генерується для кожного виклику, спільний для обох записів|
|`mcp.protocol.version`|обидва|Узгоджена ревізія|
|`mcp.session.id`|обидва|Ідентифікатор сеансу (відсутній для запитів HTTP без сеансу)|
|`stackql.mode`|обидва|Режим сервера|
|`stackql.decision`|обидва|Значення `decision` з таблиці вище|
|`stackql.query`|виклик інструмента|Дослівний SQL, для інструментів запитів|
|`stackql.query_class`|виклик інструмента|Значення `query_class`|
|`stackql.provider`|виклик інструмента|Провайдер, для інструментів метаданих|
|`stackql.query.source`|виклик інструмента|Ідентифікатор запису Query Library, якщо його надано|
|`stackql.duration_ms`|виклик інструмента|Фактична тривалість|
|`stackql.rows_returned`|виклик інструмента|Кількість рядків, для інструментів, що повертають рядки|
|`error.type`, `error.message`|виклик інструмента|У разі збою: рішення про відхилення або `tool_error` після контролю|

Тіло - `execute_tool <tool>` / `elicitation <tool>`; рівень серйозності - `INFO` або `ERROR`, якщо виклик не вдався чи був відхилений.  Контракт приховування даних однаковий в обох форматах: значення результатів ніколи не серіалізуються, лише інструкція, яка їх створила.

#### Режими збою

Коли місце призначення повертає помилку, поведінка відповіді залежить від `audit.failure_mode`.

| failure_mode | Ефект |
|--|--|
|`strict` (за замовчуванням)|Виклик інструмента повертає клієнту помилку аудиту, навіть якщо сам інструмент виконався успішно.  Це навмисно: краще неоднозначна відповідь клієнту, ніж непомічений `DELETE`.|
|`strict_mutations`|Читання `SELECT` / метаданих виконуються з приміткою в stderr; операції змінення даних і операції життєвого циклу повертають помилку аудиту.|
|`best_effort`|Помилка завжди записується в stderr, і виконання продовжується.|

#### Послідовність

Запис аудиту відбувається **після** виконання інструмента (або його відхилення контролем), але **до** повернення відповіді клієнту.  У суворому режимі збій запису аудиту під час успішного DELETE означає, що рядок видалено, але клієнт отримує помилку - так задумано, щоб жодна операція змінення даних не пройшла без аудиту.

#### Вимкнення аудиту

Щоб повністю вимкнути аудит, як у випусках до `v0.10.474`, у яких аудиту не було:

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "audit": {"disabled": true}}}'
```

* * *

### Доступні інструменти MCP

Під час роботи як сервер MCP StackQL надає такі інструменти з урахуванням налаштованого списку дозволених `enabled_tools`. Кожен повертає і текстове відображення (для LLM), і типізоване структуроване корисне навантаження (для програмних клієнтів). За замовчуванням текст відображається як таблиця markdown для однорідних багаторядкових результатів або як блок markdown KV для розріджених результатів чи результатів з одним записом. Інструменти з аргументами приймають необов'язкове перевизначення `format` (`markdown` або `json`); інакше використовується налаштування відображення сервера. У вхідних даних нижче наведено аргументи, специфічні для завдання; `?` позначає необов'язкові вхідні дані.

Клацніть ім'я будь-якого інструмента, щоб відкрити повну довідкову сторінку з вхідними даними, поведінкою контролю та прикладом промпту.

| Інструмент | Засіб відображення | Опис | Вхідні дані |
|--|--|--|--|
|[`server_info`](/mcp/server_info)|KV|Ідентичність сервера й середовище виконання: версія stackql, базовий рушій SQL, розташування реєстру провайдерів, режим, прапорець режиму лише для читання.  Викликайте на вимогу, наприклад, щоб діагностувати відхилену або контрольовану операцію чи перевірити поведінку, що залежить від версії.|немає|
|[`list_providers`](/mcp/list_providers)|Таблиця|Провайдери, уже завантажені в локальний кеш, - верхній рівень ієрархії.|немає|
|[`list_services`](/mcp/list_services)|Таблиця|Сервіси провайдера.|`provider`|
|[`list_resources`](/mcp/list_resources)|Таблиця|Ресурси в `provider`.`service`.|`provider`, `service`|
|[`list_methods`](/mcp/list_methods)|Таблиця|Методи доступу (операції HTTP) ресурсу з дієсловом SQL, якому відповідає кожен метод, і його обов'язковими параметрами.  Викликайте перед написанням будь-якого запиту - саме тут з'ясовуються обов'язкові параметри `WHERE`.|`provider`, `service`, `resource`|
|[`describe_method`](/mcp/describe_method)|KV|Повний контракт вхідних і вихідних даних одного методу (завжди EXTENDED): обов'язкові й необов'язкові вхідні дані та вихідні поля, на які може посилатися `SELECT`.|`provider`, `service`, `resource`, `method`|
|[`query_library_search`](/mcp/query_library_search)|Таблиця|Пошук відібраних шаблонів запитів за наміром, сформульованим природною мовою. Лише читання; записи, що змінюють дані, потребують явного ввімкнення й виключаються в режимі `read_only`.|`intent`, `provider?`, `service?`, `tags?`, `include_mutations?`, `limit?`|
|[`query_library_get`](/mcp/query_library_get)|KV|Отримання шаблону та оголошень його параметрів. З непорожнім `params` перевіряє значення й повертає сформований SQL разом із `next_tool`, не виконуючи його.|`id`, `params?`|
|[`validate_select_query`](/mcp/validate_select_query)|KV|Синтаксичний аналіз і планування однієї інструкції `SELECT` без виконання.  Повертає `{valid, errors}`.  Лише `SELECT`; рівно одна інструкція.|`sql`|
|[`run_select_query`](/mcp/run_select_query)|Таблиця|Виконання `SELECT`.  Повертає `{rows}`.  Лише читання.|`sql`, `row_limit?`|
|[`run_mutation_query`](/mcp/run_mutation_query)|KV|Виконання `INSERT`/`UPDATE`/`REPLACE`/`DELETE` для провайдера.  **Реальні побічні ефекти.** Повертає `{messages, timestamp}`.  Контролюється [режимом](#server-modes) сервера.|`sql`|
|[`run_lifecycle_operation`](/mcp/run_lifecycle_operation)|KV|Виконання операції життєвого циклу stackql `EXEC`.  Повертає `{messages, timestamp}`.  Контролюється [режимом](#server-modes) сервера.|`sql`|
|[`list_registry`](/mcp/list_registry)|Таблиця|Провайдери (та їхні версії), доступні в налаштованому реєстрі.  На відміну від `list_providers`, який перелічує лише вже завантажені провайдери.|`provider?`|
|[`pull_provider`](/mcp/pull_provider)|KV|Встановлення одного провайдера з реєстру в локальний кеш.  Змінює лише стан локального кешу - жодного впливу на площину керування чи площину даних хмари.|`provider`, `version?`|
|[`reload_credentials`](/mcp/reload_credentials)|Таблиця|Повторне завантаження облікових даних із файлу dotenv `--env.file` у середовище процесу та звіт про стан визначення для кожного провайдера (`ok`, `unresolved`, `not_checked`).  Ніколи не повертає секретні значення.  Дозволено в усіх режимах.|`provider?`|

Перш ніж писати SQL з нуля, зверніться до `query_library_search`, а потім скористайтеся `query_library_get`, щоб переглянути й сформувати відповідний шаблон. Інструменти запитів також приймають необов'язковий `source` з ідентифікатором запису бібліотеки лише для атрибуції; виконання й далі підлягає звичайному режиму сервера та політиці схвалення.

:::note

`describe_resource` вилучено в StackQL `v0.12.732`; клієнти MCP, промпти або вказівки для агентів, які його викликали, мають натомість викликати [`list_methods`](/mcp/list_methods), а потім `describe_method`.  Ресурс не має єдиного списку полів, оскільки кожен метод доступу повертає власну форму, тому імена стовпців беруться з [`describe_method`](/mcp/describe_method) для методу, до якого спрямовується запит.  Інструкція SQL [`DESCRIBE`](/language-spec/describe) не змінилася.

:::

### Доступні промпти MCP

Публікується один статичний промпт.

| Промпт | Опис |
|--|--|
|`write_safe_select`|Рекомендації щодо написання безпечних запитів `SELECT` до ресурсів stackql.  Пояснює, як за допомогою `SHOW METHODS IN <provider>.<service>.<resource>` знайти правильний метод читання й обов'язкові параметри `WHERE`.|

* * *

### Прапорці

| Прапорець | Опис |
|--|--|
|`--mcp.server.type`|Тип сервера MCP: `http`, `stdio` або `reverse_proxy` (останній використовується з `stackql srv`).|
|`--mcp.config`|Об'єкт конфігурації JSON для сервера MCP.  Також приймається YAML.|
|`--mcp.log.format`|Кодування журналу аудиту: `jsonl` (за замовчуванням) або `otel` (записи журналу OpenTelemetry у форматі OTLP/JSON).  Перевизначає `server.audit.format`.  Див. [Формат журналу](#log-format).|
|`--mcp.protocol.version`|Найновіша ревізія протоколу, що оголошується: `auto` (за замовчуванням), `2026-07-28` або старіша ревізія, наприклад `2025-11-25`.  Див. [Закріплення ревізії](#pinning-the-revision).|
|`--env.file`|Файл облікових даних у стилі dotenv, що завантажується під час запуску й повторно завантажується на вимогу інструментом `reload_credentials`.  Див. [(Повторне) завантаження облікових даних](#credential-resourcing---envfile--reload_credentials).|
|`--pgsrv.port`|Порт TCP для сервера мережевого протоколу PostgreSQL (використовується з `stackql srv`).|
|`-h`, `--help`|Виведення довідки.|
|`-v`, `--verbose`|Запуск у докладному режимі з додатковим виводом.|

&nbsp;
&nbsp;
> додаткові параметри див. на сторінці [Глобальні прапорці](/command-line-usage/global-flags)

:::info

Перед запуском сервера MCP потрібно встановити змінні середовища, необхідні для автентифікації провайдера, або вказати файл облікових даних у стилі dotenv за допомогою [`--env.file`](#credential-resourcing---envfile--reload_credentials).  Докладніше див. [Використання провайдера](/getting-started/using-a-provider).

:::

* * *

### Приклади

#### Базовий автономний сервер MCP

Запустіть автономний сервер MCP з автентифікацією провайдера й токеном bearer для його клієнтів:

```bash
export GOOGLE_CREDENTIALS=$(cat /path/to/google-credentials.json)
export STACKQL_MCP_TOKEN="$(openssl rand -hex 32)"

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "auth_token_env_var": "STACKQL_MCP_TOKEN"}}' \
  --registry='{"url": "https://registry.stackql.app/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'
```

#### Сервер MCP із сервером PostgreSQL (у пам'яті)

Запустіть сервери MCP і PostgreSQL для доступу за двома протоколами:

```bash
export GOOGLE_CREDENTIALS=$(cat /path/to/google-credentials.json)

stackql srv \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}' \
  --pgsrv.port 5665 \
  --registry='{"url": "https://registry.stackql.app/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'
```

#### Сервер інвентаризації лише для читання з аудитом у відомий шлях

Підходить для агента інвентаризації, який ніколи не повинен змінювати дані:

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "allow_unauthenticated": true,
      "mode": "read_only",
      "audit": {"file": {"path": "/var/log/stackql-mcp-audit.log"}}
    }
  }' \
  --registry='{"url": "https://registry.stackql.app/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'
```

#### Сервер автоматизації з повним доступом

Для довірених конвеєрів автоматизації, яким потрібні операції змінення даних і які не можуть відповідати на запити elicitation.  Конвеєр надає токен bearer, що зберігається в `STACKQL_MCP_TOKEN`:

```bash
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "auth_token_env_var": "STACKQL_MCP_TOKEN",
      "mode": "full_access"
    }
  }' \
  --registry='{"url": "https://registry.stackql.app/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'
```

#### Захищений сервер MCP із TLS

Запустіть сервер MCP із шифруванням TLS у режимі зворотного проксі:

Спочатку згенеруйте сертифікати TLS (самопідписані для розробки):

```bash
openssl req -x509 -newkey rsa:4096 -keyout server_key.pem -out server_cert.pem -days 365 -nodes
```

Потім запустіть сервер:

```bash
export STACKQL_MCP_TOKEN="$(openssl rand -hex 32)"

stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{
    "server": {
      "tls_cert_file": "server_cert.pem",
      "tls_key_file": "server_key.pem",
      "transport": "http",
      "address": "127.0.0.1:9004",
      "auth_token_env_var": "STACKQL_MCP_TOKEN"
    },
    "backend": {
      "dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"
    }
  }' \
  --pgsrv.port 5446 \
  --registry='{"url": "https://registry.stackql.app/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'
```

* * *

### Тестування вашого сервера MCP

Репозиторій містить клієнт MCP для розробки (`stackql_mcp_client`) для скриптів і регресійних тестів.  Зберіть його за допомогою команди:

```bash
python cicd/python/build.py --build-mcp-client
```

Ця команда створює `./build/stackql_mcp_client`.

Зверніть увагу, що `stackql_mcp_client` не надсилає заголовок `Authorization`, тому сервер, з яким він працює, має встановити `"allow_unauthenticated": true` (як у прикладах вище); сервер, захищений токеном, відповідає йому кодом `401`.  Він також **не** оголошує можливість elicitation MCP - він призначений для неінтерактивних скриптів.  Від сервера `safe` він отримає відмову "client does not support elicitation" для викликів змінення даних і життєвого циклу; від сервера `delete_safe` - для викликів `DELETE` та `EXEC`.  Для інтерактивного тестування із запитами elicitation використовуйте клієнт MCP, вбудований у редактор (Claude Desktop, Cursor, Continue).

```bash
# List all available tools
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912

# Server identity, mode, audit / registry context
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action server_info

# Re-source the --env.file credentials file and report per-provider
# credential status - a good first diagnostic when queries fail on auth
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action reload_credentials

# List providers already pulled into the local cache
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_providers

# List providers (and versions) available in the registry
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_registry

# Install a provider from the registry into the local cache
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action pull_provider \
  --exec.args '{"provider": "kafka"}'

# List services for a provider
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_services \
  --exec.args '{"provider": "google"}'

# List access methods for a resource (this is how an agent finds required
# WHERE parameters before writing a query)
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_methods \
  --exec.args '{"provider": "google", "service": "compute", "resource": "networks"}'

# Validate a SELECT without executing
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action validate_select_query \
  --exec.args '{"sql": "select name from google.compute.networks where project = '"'"'my-project'"'"';"}'

# Execute a SELECT
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action run_select_query \
  --exec.args '{"sql": "select name from google.compute.networks where project = '"'"'my-project'"'"';"}'

# Mutation (a DELETE) - succeeds only against a full_access server:
# stackql_mcp_client does not support elicitation, so safe and delete_safe
# servers refuse it.
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action run_mutation_query \
  --exec.args '{"sql": "delete from google.compute.firewalls where project = '"'"'my-project'"'"' and firewall = '"'"'old-rule'"'"';"}'
```

#### Приклади відповідей

`server_info` (для сервера в режимі за замовчуванням, StackQL `v1.0.888` у Windows через stdio):

```json
{
  "version": "1.0.888",
  "commit": "f7b4116",
  "build_date": "2026-11-05T00:26:03Z",
  "platform": "Windows",
  "transport": "stdio",
  "sql_backend": "sqlite3",
  "provider_registry": "https://registry.stackql.app/providers",
  "mode": "safe",
  "is_read_only": false
}
```

`run_select_query`:

```json
{
  "rows": [
    {"name": "default"},
    {"name": "pathfinders-test-01"},
    {"name": "returning-test-03"}
  ]
}
```

`run_mutation_query` (для сервера `full_access`):

```json
{
  "messages": ["The operation was despatched successfully"],
  "timestamp": "2026-05-16T10:47:33+10:00 AEST"
}
```

Зразок рядка журналу аудиту для тієї самої операції змінення даних:

```json
{"timestamp":"2026-05-16T00:47:33Z","tool":"run_mutation_query","mode":"full_access","decision":"allow","query_class":"mutation_delete","sql":"delete from google.compute.firewalls where project = 'my-project' and firewall = 'old-rule';","args":{"sql":"delete from google.compute.firewalls where project = 'my-project' and firewall = 'old-rule';","row_limit":0},"duration_ms":42}
```

* * *

### Інтеграція з асистентами ШІ

Щоб інтегрувати сервер MCP StackQL з асистентом ШІ, зареєструйте `stackql` як сервер MCP у конфігурації асистента.  Більшість клієнтів MCP, вбудованих у редактори, запускають сервер через `stdio`; для них використовуйте `--mcp.server.type=stdio`, і асистент запускатиме процес безпосередньо.  Автономні агенти, що працюють через HTTP, можуть під'єднуватися до тривалого процесу `stackql mcp --mcp.server.type=http`.

Відомості про Claude Desktop, зокрема про сторінку в каталозі Anthropic Connector Directory (рекомендований спосіб встановлення), MCP Bundle (`.mcpb`) для завантаження та ручне налаштування, див. на сторінці [Використання StackQL із Claude Desktop](/getting-started/claude-desktop).

:::note

Розташування конфігураційних файлів залежить від операційної системи та асистента ШІ.  Правильний шлях і формат див. у документації вашого асистента ШІ.

:::

* * *

### Архітектурні міркування

Вибираючи режим розгортання, враховуйте:

1. **Автономний (`stackql mcp`)**: найпростіше налаштування, ідеальне для розробки та для клієнтів, вбудованих у редактори, через `stdio`.
2. **Подвійний сервер у пам'яті (`stackql srv` з `mcp.server.type=http`)**: один процес обслуговує обидва мережеві протоколи, MCP і PostgreSQL.  Найкраща продуктивність, підходить для більшості розгортань у робочому середовищі.
3. **Зворотний проксі (`stackql srv` з `mcp.server.type=reverse_proxy`)**:
   - дає змогу розділяти навантаження між процесами або хостами
   - підтримує шифрування TLS для захищених кінцевих точок MCP
   - дає змогу незалежно масштабувати інтерфейси MCP і PostgreSQL
   - забезпечує гнучкість для інтеграції з корпоративними центрами сертифікації (примітка: підтримка корпоративних центрів сертифікації експериментальна)

Окремо щодо безпеки:

- Почніть зі значення за замовчуванням `mode: safe`.  Клієнти з підтримкою elicitation (Claude Desktop, Cursor, Continue) запитуватимуть схвалення користувача перед будь-якою операцією змінення даних.
- Закріплюйте `mode: read_only` для агентів інвентаризації чи аналітики, які ніколи не повинні виконувати операції запису.
- Закріплюйте `mode: delete_safe`, коли потрібна свобода створення й оновлення, але для деструктивних операцій потрібна участь людини.
- Залишайте `mode: full_access` для довірених конвеєрів автоматизації і лише разом із журналом аудиту, який хтось переглядає.
- Встановлюйте `server.auth_token_env_var` для будь-якого прослуховувача HTTP, до якого можуть звертатися інші процеси або хости; `allow_unauthenticated` призначено для локальної розробки.  Сам лише TLS не автентифікує клієнтів.

:::caution

Під час використання TLS із корпоративними центрами сертифікації (CA) може знадобитися додаткова конфігурація.  Ця можливість експериментальна, і її, можливо, доведеться налаштувати відповідно до реалізації вашого центру сертифікації.

:::

* * *

### Додаткові матеріали

- Довідник для розробників пакета - [README `pkg/mcp_server`](https://github.com/stackql/stackql/blob/main/pkg/mcp_server/README.md) у репозиторії stackql.
- Технічний документ для учасників розміщено в [`docs/mcp.md`](https://github.com/stackql/stackql/blob/main/docs/mcp.md) у репозиторії stackql; він містить приклади відповідей для кожного інструмента.
