Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.
mcp
Команда для запуску StackQL як сервера Model Context Protocol (MCP), що дає змогу агентам і асистентам ШІ взаємодіяти з хмарною інфраструктурою за допомогою можливостей StackQL для виконання запитів.
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 / REPLACE | DELETE | EXEC (життєвий цикл) |
|---|---|---|---|---|
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 | Режим сервера, чинний на момент виклику. |
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 за розміром / віком / кількістю резервних копій.
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_info | KV | Ідентичність сервера й середовище виконання: версія stackql, базовий рушій SQL, розташування реєстру провайдерів, режим, прапорець режиму лише для читання. Викликайте на вимогу, наприклад, щоб діагностувати відхилену або контрольовану операцію чи перевірити поведінку, що залежить від версії. | немає |
list_providers | Таблиця | Провайдери, уже завантажені в локальний кеш, - верхній рівень ієрархії. | немає |
list_services | Таблиця | Сервіси провайдера. | provider |
list_resources | Таблиця | Ресурси в provider.service. | provider, service |
list_methods | Таблиця | Методи доступу (операції HTTP) ресурсу з дієсловом SQL, якому відповідає кожен метод, і його обов'язковими параметрами. Викликайте перед написанням будь-якого запиту - саме тут з'ясовуються обов'язкові параметри WHERE. | provider, service, resource |
describe_method | KV | Повний контракт вхідних і вихідних даних одного методу (завжди EXTENDED): обов'язкові й необов'язкові вхідні дані та вихідні поля, на які може посилатися SELECT. | provider, service, resource, method |
query_library_search | Таблиця | Пошук відібраних шаблонів запитів за наміром, сформульованим природною мовою. Лише читання; записи, що змінюють дані, потребують явного ввімкнення й виключаються в режимі read_only. | intent, provider?, service?, tags?, include_mutations?, limit? |
query_library_get | KV | Отримання шаблону та оголошень його параметрів. З непорожнім params перевіряє значення й повертає сформований SQL разом із next_tool, не виконуючи його. | id, params? |
validate_select_query | KV | Синтаксичний аналіз і планування однієї інструкції SELECT без виконання. Повертає {valid, errors}. Лише SELECT; рівно одна інструкція. | sql |
run_select_query | Таблиця | Виконання SELECT. Повертає {rows}. Лише читання. | sql, row_limit? |
run_mutation_query | KV | Виконання INSERT/UPDATE/REPLACE/DELETE для провайдера. Реальні побічні ефекти. Повертає {messages, timestamp}. Контролюється режимом сервера. | sql |
run_lifecycle_operation | KV | Виконання операції життєвого циклу stackql EXEC. Повертає {messages, timestamp}. Контролюється режимом сервера. | sql |
list_registry | Таблиця | Провайдери (та їхні версії), доступні в налаштованому реєстрі. На відміну від list_providers, який перелічує лише вже завантажені провайдери. | provider? |
pull_provider | KV | Встановлення одного провайдера з реєстру в локальний кеш. Змінює лише стан локального кешу - жодного впливу на площину керування чи площину даних хмари. | 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.
Розташування конфігураційних файлів залежить від операційної системи та асистента ШІ. Правильний шлях і формат див. у документації вашого асистента ШІ.
Архітектурні міркування
Вибираючи режим розгортання, враховуйте:
- Автономний (
stackql mcp): найпростіше налаштування, ідеальне для розробки та для клієнтів, вбудованих у редактори, черезstdio. - Подвійний сервер у пам'яті (
stackql srvзmcp.server.type=http): один процес обслуговує обидва мережеві протоколи, MCP і PostgreSQL. Найкраща продуктивність, підходить для більшості розгортань у робочому середовищі. - Зворотний проксі (
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; він містить приклади відповідей для кожного інструмента.