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

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

mcp

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

Що таке MCP?

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


Синтаксис​

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

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


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

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

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

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

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 одночасно із взаємодією між ними в пам'яті.

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.

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:

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 в об'єкті конфігурації. Див. Формат журналу.

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

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

Об'єкт конфігурації 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.Це поле або allow_unauthenticated, для http
server.allow_unauthenticatedЯвне ввімкнення обслуговування транспорту HTTP без автентифікації клієнтів. За замовчуванням: false.Це поле або auth_token_env_var, для http
server.modeКонтракт безпеки, який контролює операції змінення даних і операції життєвого циклу. Одне зі значень read_only, safe (за замовчуванням), delete_safe, full_access. Див. Режими сервера.Ні
server.read_onlyСтарий логічний псевдонім для mode: read_only. Якщо встановлено обидва поля, перевагу має mode.Ні
server.statelessОбслуговування Streamable HTTP без сеансів (без Mcp-Session-Id); саме так через HTTP обслуговується ревізія протоколу 2026-07-28. За замовчуванням: false. Ігнорується для stdio. Див. Підтримка ревізій протоколу.Ні
server.protocol_versionНайновіша ревізія протоколу, що оголошується: auto (за замовчуванням), 2026-07-28 або старіша ревізія, наприклад 2025-11-25. 2026-07-28 передбачає stateless для Streamable HTTP. Див. Закріплення ревізії.Ні
server.auditКонфігурація підсистеми аудиту, зокрема audit.format (jsonl або otel). Див. Журнал аудиту.Ні
Конфігурація бекенду (лише режим зворотного проксі)​
ПолеОписОбов'язковий
backend.dsnРядок підключення PostgreSQL до сервера StackQL, що слугує бекендом.Так (для reverse_proxy)

інформація

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

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

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

{
"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, і узгоджує ревізію окремо з кожним клієнтом, тож парк різних клієнтів працює з одним сервером.

РевізіяЖиттєвий циклЗапит на схвалення (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, нижче), щоб обслуговувати 2026-07-28 нативно через HTTP:

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 в об'єкті конфігурації (прапорець має перевагу) встановлює найновішу ревізію, що оголошується:

# 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)​

примітка

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

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

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

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

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

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

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

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

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

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

reload_credentials​

Інструмент 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.


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

примітка

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 чи аргументах процесу.

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"}}'
Потрібна автентифікація сервера

Обслуговування без токена потребує явного ввімкнення: встановіть "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 замінює перевірку спільного токена автентифікацією кожної сторони, що викликає: кожен запит HTTPS перевіряється за налаштованою схемою JWT, статичного токена bearer або взаємного TLS і авторизується за правилами політики. У цьому разі TLS сервера обов'язковий, автентифікація local_os через HTTP відхиляється, а для запиту без облікових даних токен із середовища сервера ніколи не використовується як резервний варіант. Керування доступом недоступне з типом сервера reverse_proxy.


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

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

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

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

Потрібне схвалення означає процес elicitation MCP, форма якого залежить від узгодженої ревізії протоколу:

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

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

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

Починаючи з v1.0, 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 для інструментів, які читають лише локальний стан. Підказки мають рекомендаційний характер для інтерфейсу клієнта; примусове застосування правил залишається за контролем політик.

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

Починаючи з випуску 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.

Приклади​

# 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 (див. Формат журналу). Аудит увімкнено за замовчуванням. Аудит відповідає на питання "що зробив агент", а не "що побачив агент" - рядки результатів інструкцій SELECT навмисно не записуються в жодному з форматів.

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

ПолеОпис
timestampФактичний час початку виклику (RFC3339).
toolІм'я інструмента (наприклад, run_select_query).
modeРежим сервера, чинний на момент виклику.
decisionallow / refuse_immediate / needs_approval_accepted / needs_approval_declined / needs_approval_cancelled / needs_approval_unavailable.
query_classselect / 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 за розміром / віком / кількістю резервних копій.

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.

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

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

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 без процесора перетворень:

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 і MCP, які мають статус 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, у яких аудиту не було:

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_infoKVІдентичність сервера й середовище виконання: версія stackql, базовий рушій SQL, розташування реєстру провайдерів, режим, прапорець режиму лише для читання. Викликайте на вимогу, наприклад, щоб діагностувати відхилену або контрольовану операцію чи перевірити поведінку, що залежить від версії.немає
list_providersТаблицяПровайдери, уже завантажені в локальний кеш, - верхній рівень ієрархії.немає
list_servicesТаблицяСервіси провайдера.provider
list_resourcesТаблицяРесурси в provider.service.provider, service
list_methodsТаблицяМетоди доступу (операції HTTP) ресурсу з дієсловом SQL, якому відповідає кожен метод, і його обов'язковими параметрами. Викликайте перед написанням будь-якого запиту - саме тут з'ясовуються обов'язкові параметри WHERE.provider, service, resource
describe_methodKVПовний контракт вхідних і вихідних даних одного методу (завжди EXTENDED): обов'язкові й необов'язкові вхідні дані та вихідні поля, на які може посилатися SELECT.provider, service, resource, method
query_library_searchТаблицяПошук відібраних шаблонів запитів за наміром, сформульованим природною мовою. Лише читання; записи, що змінюють дані, потребують явного ввімкнення й виключаються в режимі read_only.intent, provider?, service?, tags?, include_mutations?, limit?
query_library_getKVОтримання шаблону та оголошень його параметрів. З непорожнім params перевіряє значення й повертає сформований SQL разом із next_tool, не виконуючи його.id, params?
validate_select_queryKVСинтаксичний аналіз і планування однієї інструкції SELECT без виконання. Повертає {valid, errors}. Лише SELECT; рівно одна інструкція.sql
run_select_queryТаблицяВиконання SELECT. Повертає {rows}. Лише читання.sql, row_limit?
run_mutation_queryKVВиконання INSERT/UPDATE/REPLACE/DELETE для провайдера. Реальні побічні ефекти. Повертає {messages, timestamp}. Контролюється режимом сервера.sql
run_lifecycle_operationKVВиконання операції життєвого циклу stackql EXEC. Повертає {messages, timestamp}. Контролюється режимом сервера.sql
list_registryТаблицяПровайдери (та їхні версії), доступні в налаштованому реєстрі. На відміну від list_providers, який перелічує лише вже завантажені провайдери.provider?
pull_providerKVВстановлення одного провайдера з реєстру в локальний кеш. Змінює лише стан локального кешу - жодного впливу на площину керування чи площину даних хмари.provider, version?
reload_credentialsТаблицяПовторне завантаження облікових даних із файлу dotenv --env.file у середовище процесу та звіт про стан визначення для кожного провайдера (ok, unresolved, not_checked). Ніколи не повертає секретні значення. Дозволено в усіх режимах.provider?

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

примітка

describe_resource вилучено в StackQL v0.12.732; клієнти MCP, промпти або вказівки для агентів, які його викликали, мають натомість викликати list_methods, а потім describe_method. Ресурс не має єдиного списку полів, оскільки кожен метод доступу повертає власну форму, тому імена стовпців беруться з describe_method для методу, до якого спрямовується запит. Інструкція SQL 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. Див. Формат журналу.
--mcp.protocol.versionНайновіша ревізія протоколу, що оголошується: auto (за замовчуванням), 2026-07-28 або старіша ревізія, наприклад 2025-11-25. Див. Закріплення ревізії.
--env.fileФайл облікових даних у стилі dotenv, що завантажується під час запуску й повторно завантажується на вимогу інструментом reload_credentials. Див. (Повторне) завантаження облікових даних.
--pgsrv.portПорт TCP для сервера мережевого протоколу PostgreSQL (використовується з stackql srv).
-h, --helpВиведення довідки.
-v, --verboseЗапуск у докладному режимі з додатковим виводом.

   

додаткові параметри див. на сторінці Глобальні прапорці

інформація

Перед запуском сервера MCP потрібно встановити змінні середовища, необхідні для автентифікації провайдера, або вказати файл облікових даних у стилі dotenv за допомогою --env.file. Докладніше див. Використання провайдера.


Приклади​

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

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

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 для доступу за двома протоколами:

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"}}'

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

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

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:

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 (самопідписані для розробки):

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

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

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) для скриптів і регресійних тестів. Зберіть його за допомогою команди:

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).

# 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):

{
"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:

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

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

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

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

{"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.

примітка

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


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

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

  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 не автентифікує клієнтів.
обережно

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


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

  • Довідник для розробників пакета - README pkg/mcp_server у репозиторії stackql.
  • Технічний документ для учасників розміщено в docs/mcp.md у репозиторії stackql; він містить приклади відповідей для кожного інструмента.