Chuyển tới nội dung chính
Trang được dịch

Trang này được dịch từ tiếng Anh với sự hỗ trợ của AI. Nếu hai bản có chỗ khác nhau, hãy lấy phiên bản tiếng Anh làm chuẩn.

mcp

Lệnh dùng để khởi chạy StackQL làm máy chủ Model Context Protocol (MCP), cho phép tác nhân AI và trợ lý AI tương tác với hạ tầng đám mây bằng các khả năng truy vấn của StackQL.

MCP là gì?

Model Context Protocol (MCP) là một giao thức mở chuẩn hóa cách các ứng dụng AI tương tác với nguồn dữ liệu và công cụ bên ngoài. Khi chạy StackQL làm máy chủ MCP, bạn có thể cho phép tác nhân AI (Claude, Cursor, Continue, tác nhân tùy chỉnh, v.v.) truy vấn và quản lý hạ tầng đám mây trên nhiều provider bằng ngôn ngữ tự nhiên.


Cú pháp​

stackql mcp [flags] cho một máy chủ MCP độc lập.

stackql srv [flags] để chạy máy chủ MCP cùng với máy chủ giao thức wire của PostgreSQL trong cùng một tiến trình.


Chế độ triển khai​

Máy chủ MCP của StackQL có thể được triển khai theo ba cấu hình khác nhau để phù hợp với các yêu cầu kiến trúc khác nhau. Các ví dụ dưới đây chủ động bật chế độ phục vụ không xác thực bằng "allow_unauthenticated": true, phù hợp cho phát triển cục bộ; với mọi thứ mà một tiến trình hoặc máy khác có thể truy cập, hãy cấu hình bearer token thay thế (xem Xác thực ứng dụng khách HTTP).

1. Máy chủ MCP độc lập​

Chạy StackQL làm một máy chủ MCP chuyên dụng trên một cổng được chỉ định.

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

Trường hợp sử dụng: khi bạn chỉ cần truy cập qua giao thức MCP và không cần tương thích với giao thức wire của PostgreSQL.

2. Máy chủ MCP + PostgreSQL (trong bộ nhớ)​

Chạy đồng thời cả máy chủ MCP và máy chủ PostgreSQL, giao tiếp với nhau trong bộ nhớ.

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

Trường hợp sử dụng: khi bạn cần cả truy cập qua giao thức MCP cho tác nhân AI và giao thức wire của PostgreSQL cho các ứng dụng khách cơ sở dữ liệu truyền thống, với hiệu năng tối đa nhờ giao tiếp trong bộ nhớ.

3. Máy chủ MCP + PostgreSQL (reverse proxy)​

Chạy cả hai máy chủ với giao tiếp qua TCP, hỗ trợ triển khai phân tán và mã hóa 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

Với mã hóa 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 mã hóa phương thức truyền tải nhưng không xác thực ứng dụng khách, vì vậy ví dụ này cũng yêu cầu bearer token được lưu trong STACKQL_MCP_TOKEN.

Trường hợp sử dụng: khi bạn cần tách khối lượng công việc MCP và PostgreSQL ra các tiến trình hoặc máy khác nhau, hoặc khi bạn cần mã hóa TLS cho điểm cuối MCP.


Tùy chọn cấu hình​

Loại máy chủ MCP​

LoạiMô tả
httpChế độ máy chủ HTTP trực tiếp - các yêu cầu MCP được công cụ truy vấn StackQL xử lý ngay trong tiến trình.
reverse_proxyChế độ reverse proxy - các yêu cầu MCP được chuyển tới một máy chủ PostgreSQL bên dưới qua DSN đã cấu hình. Dùng với stackql srv.
stdioPhương thức truyền tải đầu vào/đầu ra chuẩn - máy chủ đọc yêu cầu từ stdin và ghi phản hồi ra stdout. Dùng cho các ứng dụng khách MCP nhúng trong trình soạn thảo (Claude Desktop, Cursor, v.v.).

Định dạng nhật ký MCP​

Cờ --mcp.log.format chọn cách mã hóa nhật ký kiểm tra: jsonl (mặc định) hoặc otel (bản ghi nhật ký OTLP/JSON của OpenTelemetry). Cờ này ghi đè server.audit.format trong đối tượng cấu hình. Xem Định dạng nhật ký.

Phiên bản giao thức MCP​

Cờ --mcp.protocol.version đặt bản sửa đổi giao thức mới nhất mà máy chủ công bố: auto (mặc định, mọi bản sửa đổi được hỗ trợ), 2026-07-28 (chỉ chế độ không có phiên) hoặc một bản sửa đổi cũ hơn như 2025-11-25 (bản sửa đổi đó và các bản trước). Cờ này ghi đè server.protocol_version trong đối tượng cấu hình. Xem Ghim phiên bản sửa đổi.

Đối tượng cấu hình MCP​

Cờ --mcp.config nhận một đối tượng JSON có cấu trúc như sau.

Cấu hình máy chủ​
TrườngMô tảBắt buộc
server.transportGiao thức truyền tải - http hoặc stdio.Có
server.addressĐịa chỉ và cổng mà máy chủ MCP liên kết (ví dụ: 127.0.0.1:9912). Chỉ cho phương thức truyền tải HTTP.Với http
server.tls_cert_fileĐường dẫn tới tệp chứng chỉ TLS cho HTTPS.Không
server.tls_key_fileĐường dẫn tới tệp khóa riêng TLS cho HTTPS.Không
server.auth_token_env_varTên của một biến môi trường chứa bearer token chia sẻ trước. Khi được đặt, mọi yêu cầu HTTP phải mang Authorization: Bearer <token>; máy chủ từ chối khởi động nếu biến chưa được đặt hoặc rỗng. Xem Xác thực ứng dụng khách HTTP.Một trong hai: trường này hoặc allow_unauthenticated, với http
server.allow_unauthenticatedBật một cách rõ ràng việc phục vụ phương thức truyền tải HTTP mà không xác thực ứng dụng khách. Mặc định: false.Một trong hai: trường này hoặc auth_token_env_var, với http
server.modeHợp đồng an toàn kiểm soát các thao tác thay đổi dữ liệu và thao tác vòng đời. Một trong read_only, safe (mặc định), delete_safe, full_access. Xem Chế độ máy chủ.Không
server.read_onlyBí danh boolean cũ cho mode: read_only. Khi cả hai trường đều được đặt, mode được ưu tiên.Không
server.statelessPhục vụ Streamable HTTP không có phiên (không có Mcp-Session-Id), đây là cách bản sửa đổi giao thức 2026-07-28 được phục vụ qua HTTP. Mặc định: false. Bị bỏ qua với stdio. Xem Hỗ trợ bản sửa đổi giao thức.Không
server.protocol_versionBản sửa đổi giao thức mới nhất được công bố: auto (mặc định), 2026-07-28 hoặc một bản sửa đổi cũ hơn như 2025-11-25. 2026-07-28 ngụ ý stateless với Streamable HTTP. Xem Ghim phiên bản sửa đổi.Không
server.auditCấu hình hệ thống con kiểm tra, bao gồm audit.format (jsonl hoặc otel). Xem Nhật ký kiểm tra.Không
Cấu hình backend (chỉ chế độ reverse proxy)​
TrườngMô tảBắt buộc
backend.dsnChuỗi kết nối PostgreSQL tới máy chủ StackQL backend.Có (với reverse_proxy)

thông tin

DSN backend nên bao gồm tham số default_query_exec_mode=simple_protocol để có khả năng tương thích tốt nhất.

Danh sách cho phép​
TrườngMô tả
enabled_toolsMảng tên các công cụ mà máy chủ được phép công bố. Khi bị bỏ qua hoặc rỗng, mọi công cụ tích hợp sẵn đều được đăng ký. Dùng để chỉ cung cấp một tập con hẹp (ví dụ: một máy chủ kiểm kê chỉ đọc).
enabled_promptsMảng tên lời nhắc. Cùng ngữ nghĩa với enabled_tools nhưng áp dụng cho các lời nhắc.

Ví dụ - một máy chủ chỉ công bố server_info và list_providers:

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

Hỗ trợ bản sửa đổi giao thức​

Bản sửa đổi giao thức 2026-07-28, server.stateless và định dạng nhật ký kiểm tra otel có từ StackQL v0.11.660 trở đi. server.protocol_version và cờ --mcp.protocol.version có từ StackQL v0.12.732 trở đi.

Máy chủ hiểu mọi bản sửa đổi của Model Context Protocol mà Go MCP SDK hỗ trợ và thương lượng theo từng ứng dụng khách, vì vậy một tập hợp ứng dụng khách hỗn hợp vẫn làm việc được với một máy chủ duy nhất.

Bản sửa đổiVòng đờiYêu cầu phê duyệt (safe / delete_safe)
2026-07-28 (được công bố)Không có handshake: server/discover, sau đó mọi yêu cầu mang io.modelcontextprotocol/protocolVersion và io.modelcontextprotocol/clientCapabilities trong _meta (cùng với các header Mcp-Protocol-Version, Mcp-Method và Mcp-Name trên HTTP).Kết quả input_required, được ứng dụng khách thử lại với inputResponses (SEP-2322).
2025-11-25, 2025-06-18Handshake initialize / notifications/initialized.Yêu cầu elicitation/create do máy chủ khởi tạo.
2025-03-26, 2024-11-05Như trên.Như trên.

stdio phục vụ mọi bản sửa đổi trên một tiến trình: yêu cầu đầu tiên của ứng dụng khách 2026-07-28 được phục vụ mà không cần handshake, và initialize của ứng dụng khách cũ hơn vẫn hoạt động. Không cần cấu hình gì cho Claude Desktop, các trình khởi chạy npm / PyPI hay image Docker.

Streamable HTTP theo mặc định dùng mô hình có trạng thái, mỗi ứng dụng khách một phiên (Mcp-Session-Id), mà SDK phục vụ cho các bản sửa đổi tới 2025-11-25. Một yêu cầu 2026-07-28 được trả lời bằng lỗi JSON-RPC -32022 (phiên bản giao thức không được hỗ trợ; một lỗi HTTP 400 thông thường trong các bản phát hành tới v0.12.718) có data.supported liệt kê các bản sửa đổi dùng handshake, và server/discover cũng công bố như vậy, nên ứng dụng khách thương lượng xuống bản sửa đổi thấp hơn và các tích hợp HTTP hiện có giữ nguyên phiên cũng như yêu cầu phê duyệt của chúng. Đặt server.stateless (hoặc ghim bản sửa đổi ở 2026-07-28, bên dưới) để phục vụ 2026-07-28 một cách nguyên bản qua HTTP:

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

Máy chủ không có phiên không cấp Mcp-Session-Id, trả lời GET và DELETE bằng 405 (không có phiên nào để hủy), giữ tools/list, prompts/list và resources/list bất biến theo kết nối, và thực hiện vòng phê duyệt qua input_required. Máy chủ này vẫn chấp nhận initialize của ứng dụng khách cũ hơn và phục vụ các thao tác đọc cho ứng dụng khách đó, nhưng không thể giữ lại khả năng elicitation mà ứng dụng khách đó đã khai báo khi khởi tạo (mỗi yêu cầu nhận một phiên tạm thời), vì vậy trên máy chủ không có phiên, ứng dụng khách cũ hơn không thể phê duyệt các thao tác ghi cần phê duyệt. Chọn stateless cho các host dùng bản sửa đổi hiện tại và giữ mặc định cho tập hợp ứng dụng khách vẫn còn ứng dụng khách cũ hơn.

Máy chủ không giữ trạng thái giữa các lần gọi: chế độ, nhật ký kiểm tra và thông tin xác thực provider là cấu hình ở cấp tiến trình, vì vậy không có gì cần chuyển ra sau các handle tường minh.

Ghim phiên bản sửa đổi​

Theo mặc định, máy chủ công bố mọi bản sửa đổi được hỗ trợ và thương lượng theo từng ứng dụng khách. Cờ --mcp.protocol.version, hoặc server.protocol_version trong đối tượng cấu hình (cờ được ưu tiên), đặt bản sửa đổi mới nhất được công bố:

# 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
Giá trịĐược công bốTác dụng
auto (mặc định) hoặc không đặtMọi bản sửa đổi được hỗ trợ.Thương lượng như trên: bản sửa đổi cao nhất mà cả hai bên đều hỗ trợ.
2026-07-28Chỉ 2026-07-28.Chỉ chế độ không có phiên, và stateless được ngụ ý với Streamable HTTP. initialize của ứng dụng khách cũ hơn được trả lời bằng 2025-11-25, tín hiệu để ứng dụng khách đó ngắt kết nối thay vì đọc câu trả lời như vòng đời mới.
2025-11-25 (hoặc bất kỳ bản sửa đổi cũ hơn nào)Bản sửa đổi đó và mọi bản trước nó.Chỉ vòng đời dùng handshake: một yêu cầu 2026-07-28 nhận lỗi JSON-RPC -32022 có data.supported liệt kê các bản sửa đổi được công bố, để ứng dụng khách có thể thương lượng lại. Các ứng dụng khách dùng handshake cũ hơn giữ bản sửa đổi của riêng chúng.

Mọi giá trị khác đều không vượt qua bước kiểm tra tính hợp lệ của cấu hình khi khởi động, và thông báo lỗi nêu tên các giá trị hợp lệ.

Giới hạn truyền tải​

Phần thân yêu cầu Streamable HTTP bị giới hạn ở 4 MiB (HTTP 413 nếu vượt quá), JSON lồng nhau sâu hơn 1000 cấp bị từ chối trước khi phân tích cú pháp, và một frame stdio đơn lẻ bị giới hạn ở 8 MiB. Không giới hạn nào trong số này có thể cấu hình; tất cả đều cao hơn nhiều so với mọi câu lệnh SQL mà máy chủ chấp nhận.


Nạp (lại) thông tin xác thực (--env.file + reload_credentials)​

ghi chú

--env.file và công cụ reload_credentials có trong các bản phát hành StackQL sau v0.10.542.

Khối biến môi trường của một tiến trình được cố định khi tiến trình được tạo. Điều này gây ra hai vấn đề cho máy chủ MCP:

  • Một máy chủ MCP stdio do một ứng dụng khách trên máy tính (Claude Desktop, Cursor, v.v.) khởi tạo mà không có các biến môi trường chứa thông tin xác thực sẽ không bao giờ thấy được chúng - ứng dụng khách truyền môi trường của chính nó cho tiến trình con.
  • Thông tin xác thực ngắn hạn sau khi được xoay vòng không bao giờ đến được một phiên máy chủ chạy lâu dài.

Cờ --env.file khắc phục cả hai vấn đề bằng cách chỉ định một tệp kiểu dotenv đóng vai trò kho thông tin xác thực có thể thay đổi:

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

Ngữ nghĩa nạp tệp​

Tệp được nạp vào môi trường tiến trình khi khởi động với mọi điểm vào (exec, shell, srv, registry, mcp):

  • Khi cờ rỗng hoặc không được đặt, không có gì xảy ra - thông tin xác thực được phân giải trễ từ môi trường tiến trình tại thời điểm yêu cầu, đúng như hành vi trước đây.
  • Tệp không tồn tại tại đường dẫn đã cho được chấp nhận và không làm gì cả (tệp có thể được tạo sau).
  • Tệp sai định dạng hoặc không đọc được gây lỗi nghiêm trọng khi khởi động.
  • Chỉ các khóa có giá trị không rỗng mới được đặt; các biến môi trường hiện có của tiến trình có bị ghi đè (tệp là nguồn dữ liệu gốc); không bao giờ có biến nào bị hủy thiết lập.
  • Cờ này chỉ dùng trên dòng lệnh - cờ không được nạp từ .stackqlrc.

Định dạng tệp là một KEY=VALUE trên mỗi dòng. Chú thích #, dòng trống, tiền tố export không bắt buộc, dấu nháy đơn hoặc nháy kép không bắt buộc quanh giá trị, và ký tự kết thúc dòng CRLF đều được chấp nhận:

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

reload_credentials​

Công cụ reload_credentials nạp lại tệp --env.file vào môi trường tiến trình giữa phiên, sau đó báo cáo trạng thái phân giải thông tin xác thực theo từng provider. Giá trị bí mật không bao giờ được trả về, ghi nhật ký hay ghi vào nhật ký kiểm tra - chỉ có tên và trạng thái. Khi chưa cấu hình --env.file, công cụ chỉ còn là một phép thăm dò trạng thái.

Khi một truy vấn thất bại do phân giải thông tin xác thực, lỗi MCP mang một gợi ý hướng dẫn tác nhân gọi reload_credentials và thử lại, nhờ vậy các ứng dụng khách dựa trên tác nhân tự khắc phục: ghi thông tin xác thực vào tệp, yêu cầu tác nhân tải lại, và truy vấn bị lỗi sẽ thành công khi thử lại - không cần khởi động lại máy chủ.

reload_credentials không được hỗ trợ ở chế độ backend reverse_proxy - truy vấn được thực thi trong tiến trình máy chủ stackql từ xa, vì vậy công cụ trả về lỗi hướng dẫn người dùng tải lại trên máy chủ bên dưới.

Windows và Claude Desktop​

setx ghi vào registry chứ không ghi vào các tiến trình đang chạy, và Claude Desktop truyền môi trường (đã cũ) của chính nó cho các tiến trình con MCP - vì vậy thay đổi thông tin xác thực thường đòi hỏi khởi động lại hoàn toàn Claude Desktop. Với --env.file, tệp thông tin xác thực có thể được tạo hoặc xoay vòng bất cứ lúc nào và reload_credentials nhận thay đổi mà không cần khởi động lại. Xem Sử dụng StackQL với Claude Desktop để biết một cấu hình mẫu hoàn chỉnh.


Xác thực ứng dụng khách HTTP​

ghi chú

server.auth_token_env_var và server.allow_unauthenticated có từ StackQL v0.12.742 trở đi.

Phương thức truyền tải HTTP yêu cầu xác thực ứng dụng khách. server.auth_token_env_var chỉ định tên một biến môi trường chứa bearer token chia sẻ trước; mọi yêu cầu phải mang Authorization: Bearer <token>, nếu không sẽ được trả lời bằng 401. Token được đọc từ môi trường, vì vậy token không bao giờ xuất hiện trong --mcp.config hay trong đối số của tiến trình.

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"}}'
Bắt buộc xác thực trên máy chủ

Phục vụ không có token phải được bật một cách rõ ràng: đặt "allow_unauthenticated": true trong server. Nếu không có khóa nào trong hai khóa này, máy chủ thoát khi khởi động với thông báo nêu tên cả hai; máy chủ cũng thoát nếu biến token chưa được đặt hoặc rỗng. Kể từ bản phát hành v0.12.742, bạn phải thêm auth_token_env_var hoặc "allow_unauthenticated": true vào server khi dùng phương thức truyền tải http.

TLS (tls_cert_file / tls_key_file) mã hóa phương thức truyền tải nhưng không xác thực ứng dụng khách; hãy kết hợp TLS với token cho mọi listener ngoài loopback. Các yêu cầu từ trình duyệt khác nguồn gốc (Origin không khớp, hoặc Sec-Fetch-Site là cross-site) bị từ chối với 403 bất kể xác thực. stackql_mcp_client đi kèm không gửi header Authorization, vì vậy máy chủ mà nó điều khiển phải chủ động bật chế độ phục vụ không xác thực.

Từ v1.0, khởi động máy chủ với --access.config sẽ thay cơ chế kiểm soát bằng token dùng chung bằng xác thực theo từng bên gọi: mỗi yêu cầu HTTPS được xác minh bằng cơ chế JWT, bearer tĩnh hoặc TLS hai chiều đã cấu hình và được ủy quyền theo các quy tắc chính sách. Khi đó TLS phía máy chủ là bắt buộc, xác thực local_os bị từ chối qua HTTP, và một yêu cầu không có thông tin xác thực không bao giờ quay về dùng token trong môi trường của máy chủ. Quản lý truy cập không khả dụng với loại máy chủ reverse_proxy.


Chế độ máy chủ​

server.mode chọn một trong bốn hợp đồng an toàn. Cả bốn đều cho phép SELECT và các thao tác đọc siêu dữ liệu; chúng khác nhau ở cách xử lý các thao tác thay đổi dữ liệu và thao tác vòng đời.

Chế độSELECT / siêu dữ liệuINSERT / UPDATE / REPLACEDELETEEXEC (vòng đời)
read_onlycho phéptừ chốitừ chốitừ chối
safe (mặc định)cho phépcần phê duyệtcần phê duyệtcần phê duyệt
delete_safecho phépcho phépcần phê duyệtcần phê duyệt
full_accesscho phépcho phépcho phépcho phép

Từ chối trả về lỗi ngay lập tức cho ứng dụng khách.

Cần phê duyệt dùng luồng elicitation của MCP, được định hình bởi bản sửa đổi giao thức đã thương lượng:

  • Nếu ứng dụng khách đã công bố khả năng elicitation (khi khởi tạo, hoặc trong các khả năng của ứng dụng khách ở _meta theo từng yêu cầu trên 2026-07-28), máy chủ yêu cầu người dùng phê duyệt hành động bằng một thông báo ngắn (tên công cụ, loại truy vấn, SQL). Trên 2026-07-28, yêu cầu phê duyệt được trả về dưới dạng kết quả input_required mang một yêu cầu đầu vào elicitation/create với ID stackql_approval, và ứng dụng khách thử lại lệnh gọi với câu trả lời trong inputResponses; trên các bản sửa đổi trước đó, máy chủ tự gửi yêu cầu elicitation/create giữa lệnh gọi. Người dùng chấp nhận, từ chối hoặc hủy.
  • Nếu ứng dụng khách không công bố elicitation, công cụ bị từ chối với một thông báo giải thích điểm thiếu hụt và hướng người vận hành tới chế độ full_access.

Ứng dụng khách là bên trả lời yêu cầu phê duyệt, vì vậy cơ chế này bảo vệ trước việc tác nhân hành động mà không có người dùng của nó, chứ không bảo vệ trước một bên gọi không đáng tin cậy. Kết hợp phương thức truyền tải HTTP với xác thực ứng dụng khách khi bên gọi không đáng tin cậy.

Chế độ áp dụng toàn cục cho mỗi máy chủ. Không có ghi đè theo từng công cụ.

Từ v1.0, run_select_query từ chối INSERT, UPDATE, REPLACE, DELETE và EXEC ở mọi chế độ, kể cả full_access; thông báo lỗi nêu tên run_mutation_query hoặc run_lifecycle_operation. Mọi công cụ cũng mang một title và bốn gợi ý hành vi MCP dưới dạng boolean tường minh (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), được suy ra từ cùng cách phân loại mà cơ chế kiểm soát chính sách thực thi. openWorldHint là true cho list_registry, pull_provider, run_select_query, run_mutation_query và run_lifecycle_operation, là những công cụ truy cập điểm cuối của registry hoặc provider, và false cho các công cụ chỉ đọc trạng thái cục bộ. Các gợi ý chỉ mang tính tham khảo cho trải nghiệm người dùng phía ứng dụng khách; việc thực thi vẫn thuộc về cơ chế kiểm soát chính sách.

Kiểm soát payload

Từ bản phát hành v0.12.742, một payload chứa nhiều câu lệnh được kiểm soát theo câu lệnh có đặc quyền cao nhất của nó ở mọi chế độ, vì vậy SELECT 1; DELETE ... được xử lý như một DELETE và bản ghi kiểm tra mang query_class mutation_delete. validate_select_query chỉ chấp nhận đúng một câu lệnh.

Thay đổi hành vi của chế độ mặc định​

Các bản phát hành trước chỉ thực thi an toàn qua một cờ read_only: true/false duy nhất có mặc định là "không thực thi". Mặc định hiện tại (mode: safe) khiến các thao tác thay đổi dữ liệu cần người dùng phê duyệt ngay từ đầu. Người vận hành chạy một ứng dụng khách MCP hỗ trợ elicitation (Claude Desktop, Cursor, Continue, v.v.) sẽ thấy một yêu cầu phê duyệt cho mỗi thao tác thay đổi dữ liệu. Người vận hành chạy tự động hóa, hoặc stackql_mcp_client đi kèm (không công bố elicitation), phải chủ động bật mode: full_access một cách rõ ràng để chạy các thao tác thay đổi dữ liệu và thao tác vòng đời.

Khóa JSON / YAML cũ read_only: true vẫn được chấp nhận để tương thích ngược và được xem là tương đương với mode: read_only.

Ví dụ​

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

Nhật ký kiểm tra​

Mỗi lệnh gọi công cụ ghi một bản ghi vào đích kiểm tra đã cấu hình, theo mặc định dưới dạng JSONL hoặc dưới dạng bản ghi nhật ký OpenTelemetry (xem Định dạng nhật ký). Tính năng kiểm tra được bật theo mặc định. Nhật ký kiểm tra trả lời câu hỏi "tác nhân đã làm gì", chứ không phải "tác nhân đã thấy gì" - các hàng kết quả từ câu lệnh SELECT được cố ý không ghi lại, ở cả hai định dạng.

Những gì được ghi lại​

TrườngMô tả
timestampThời điểm bắt đầu lệnh gọi theo đồng hồ thực (RFC3339).
toolTên công cụ (ví dụ: run_select_query).
modeChế độ máy chủ có hiệu lực tại thời điểm gọi.
decisionallow / refuse_immediate / needs_approval_accepted / needs_approval_declined / needs_approval_cancelled / needs_approval_unavailable.
query_classselect / mutation_create / mutation_delete / lifecycle / unknown. Với payload chứa nhiều câu lệnh, đây là loại của câu lệnh có đặc quyền cao nhất.
sqlChuỗi SQL cho các công cụ truy vấn (run_select_query, run_mutation_query, run_lifecycle_operation, validate_select_query).
argsCác trường phân cấp cho công cụ siêu dữ liệu (list_*, describe_method); SQL + row_limit cho công cụ truy vấn.
duration_msThời lượng thực tế của cơ chế kiểm soát + trình xử lý.
errorThông báo lỗi nếu công cụ gặp lỗi hoặc bị từ chối.

Các hàng kết quả từ câu lệnh SELECT được cố ý loại trừ - chúng có thể rất lớn và có thể chứa dữ liệu nhạy cảm.

Đích tệp​

Đích duy nhất hiện có là file. Mỗi dòng một đối tượng JSON, fsync sau mỗi bản ghi, xoay vòng kiểu lumberjack theo kích thước / tuổi / số bản sao lưu.

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

Có hai cách chỉ định vị trí:

  • audit.file.path - một đường dẫn tệp đầy đủ (tuyệt đối, hoặc tương đối với cwd).
  • audit.file.dir - một thư mục; đích chọn tên tệp stackql_mcp_server_<RFC3339-utc-second>.log bên trong thư mục đó.

Khi cả hai đều không được đặt trong mcp.config, máy chủ MCP đặt mặc định dir là cwd để người vận hành hiện tại thấy hành vi như trước. Bản thân gói đích chung bên dưới từ chối tự ý chọn thư mục - quyết định "nhật ký được ghi ở đâu" luôn do bên gọi đưa ra.

Đường dẫn tuyệt đối đã phân giải được ghi ra stderr khi khởi động dưới dạng sink file: /path/to/file.log.

Định dạng nhật ký​

Luồng kiểm tra có hai cách mã hóa, được ghi vào cùng một đích tệp:

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

Cờ này ghi đè server.audit.format trong mcp.config ("audit": {"format": "otel"}). jsonl tương thích từng byte với các bản ghi mô tả ở trên. otel ghi một đối tượng OTLP/JSON LogsData trên mỗi dòng, đúng dạng mà receiver otlp_json_file của OpenTelemetry Collector tiếp nhận nguyên trạng (đã xác minh với otelcol-contrib 0.160.0), vì vậy luồng này đến được mọi pipeline OTLP mà không cần transform processor:

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

Mỗi lệnh gọi công cụ tạo ra một bản ghi nhật ký; một lệnh gọi đi qua cơ chế kiểm soát phê duyệt tạo ra bản ghi thứ hai cho quyết định elicitation. Các bản ghi của cùng một lệnh gọi dùng chung gen_ai.tool.call.id và một ID trace. traceparent W3C do bên gọi cung cấp trong params._meta sẽ được tôn trọng; nếu không, một ID trace được tạo cho mỗi phiên MCP để các bản ghi của một phiên tác nhân liên kết được với nhau.

Tập thuộc tính được phát ra là một giao diện có phiên bản: phạm vi instrumentation là github.com/stackql/stackql/pkg/mcp_server/audit ở phiên bản 1.0.0, và schemaUrl ghim các quy ước ổn định vào https://opentelemetry.io/schemas/1.44.0. Các thuộc tính gen_ai.* và mcp.* tuân theo quy ước ngữ nghĩa GenAI và MCP, vốn đang ở trạng thái Development; phiên bản phạm vi được tăng khi tập thuộc tính thay đổi.

Thuộc tínhBản ghiGiá trị
service.name, service.versiontài nguyênstackql, phiên bản StackQL
gen_ai.operation.namelệnh gọi công cụexecute_tool
mcp.method.namecả haitools/call trên bản ghi lệnh gọi công cụ, elicitation/create trên bản ghi quyết định
gen_ai.tool.namecả haiTên công cụ
gen_ai.tool.call.idcả haiĐược tạo cho mỗi lệnh gọi, dùng chung cho cả hai bản ghi
mcp.protocol.versioncả haiBản sửa đổi đã thương lượng
mcp.session.idcả haiID phiên (không có với các yêu cầu HTTP không có phiên)
stackql.modecả haiChế độ máy chủ
stackql.decisioncả haiGiá trị decision từ bảng ở trên
stackql.querylệnh gọi công cụSQL nguyên văn, cho các công cụ truy vấn
stackql.query_classlệnh gọi công cụGiá trị query_class
stackql.providerlệnh gọi công cụProvider, cho các công cụ siêu dữ liệu
stackql.query.sourcelệnh gọi công cụID mục Query Library, khi được cung cấp
stackql.duration_mslệnh gọi công cụThời lượng thực tế
stackql.rows_returnedlệnh gọi công cụSố hàng, cho các công cụ trả về hàng
error.type, error.messagelệnh gọi công cụKhi thất bại: quyết định từ chối, hoặc tool_error sau cơ chế kiểm soát

Body là execute_tool <tool> / elicitation <tool>; mức độ nghiêm trọng là INFO, hoặc ERROR khi lệnh gọi thất bại hoặc bị từ chối. Hợp đồng che giấu dữ liệu giống hệt nhau ở cả hai định dạng: giá trị kết quả không bao giờ được tuần tự hóa, chỉ có câu lệnh đã tạo ra chúng.

Chế độ xử lý lỗi​

Khi đích trả về lỗi, hành vi phản hồi phụ thuộc vào audit.failure_mode.

failure_modeTác dụng
strict (mặc định)Lệnh gọi công cụ trả về lỗi kiểm tra cho ứng dụng khách ngay cả khi công cụ bên dưới đã thành công. Đây là chủ ý: thà ứng dụng khách nhận một phản hồi không rõ ràng còn hơn một DELETE không bị phát hiện.
strict_mutationsCác thao tác đọc SELECT / siêu dữ liệu tiếp tục kèm một ghi chú trên stderr; thao tác thay đổi dữ liệu và thao tác vòng đời trả về lỗi kiểm tra.
best_effortLuôn ghi nhật ký ra stderr và tiếp tục.

Trình tự​

Thao tác ghi kiểm tra diễn ra sau khi công cụ thực thi (hoặc bị cơ chế kiểm soát chặn lại) nhưng trước khi phản hồi được trả về ứng dụng khách. Ở chế độ strict, một lỗi ghi kiểm tra đối với một DELETE thành công nghĩa là hàng đã bị xóa nhưng ứng dụng khách nhận được lỗi - đây là chủ ý thiết kế, để không có thao tác thay đổi dữ liệu nào lọt qua mà không được ghi kiểm tra.

Tắt kiểm tra​

Để tắt hoàn toàn tính năng kiểm tra, như trong các bản phát hành trước v0.10.474 vốn không có kiểm tra:

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

Các công cụ MCP hiện có​

Khi chạy làm máy chủ MCP, StackQL cung cấp các công cụ sau, tùy theo danh sách cho phép enabled_tools đã cấu hình. Mỗi công cụ trả về cả một bản hiển thị dạng văn bản (cho LLM) và một payload có cấu trúc, có kiểu (cho các ứng dụng khách lập trình). Cách hiển thị văn bản mặc định là một bảng markdown cho kết quả nhiều hàng đồng nhất hoặc một khối KV markdown cho kết quả thưa / chỉ một bản ghi. Các công cụ có đối số chấp nhận ghi đè format (markdown hoặc json) không bắt buộc; nếu không, thiết lập hiển thị của máy chủ được sử dụng. Phần đầu vào bên dưới liệt kê các đối số dành riêng cho tác vụ; ? đánh dấu đầu vào không bắt buộc.

Nhấp vào tên công cụ bất kỳ để xem trang tham khảo đầy đủ, bao gồm đầu vào, hành vi kiểm soát và một lời nhắc ví dụ.

Công cụTrình hiển thịMô tảĐầu vào
server_infoKVDanh tính và runtime của máy chủ: phiên bản stackql, công cụ SQL bên dưới, vị trí registry provider, chế độ, cờ chỉ đọc. Gọi khi cần, ví dụ để chẩn đoán một thao tác bị từ chối hoặc được kiểm soát, hoặc để kiểm tra hành vi phụ thuộc phiên bản.không có
list_providersBảngCác provider đã được tải xuống bộ nhớ đệm cục bộ - cấp cao nhất của phân cấp.không có
list_servicesBảngCác dịch vụ thuộc một provider.provider
list_resourcesBảngCác tài nguyên thuộc một provider.service.provider, service
list_methodsBảngCác phương thức truy cập (thao tác HTTP) của một tài nguyên, kèm động từ SQL mà mỗi phương thức ánh xạ tới và các tham số bắt buộc của phương thức đó. Gọi trước khi viết bất kỳ truy vấn nào - đây là nơi suy ra các tham số WHERE bắt buộc.provider, service, resource
describe_methodKVHợp đồng I/O đầy đủ của một phương thức (luôn EXTENDED): các đầu vào bắt buộc và không bắt buộc, cùng các trường đầu ra mà một SELECT có thể tham chiếu.provider, service, resource, method
query_library_searchBảngTìm các template truy vấn được tuyển chọn theo ý định diễn đạt bằng ngôn ngữ tự nhiên. Chỉ đọc; các mục thay đổi dữ liệu cần chủ động bật và bị loại trừ ở chế độ read_only.intent, provider?, service?, tags?, include_mutations?, limit?
query_library_getKVLấy một template và các khai báo tham số của nó. Với params không rỗng, kiểm tra tính hợp lệ của các giá trị và trả về SQL đã được tạo từ template cùng next_tool, mà không thực thi.id, params?
validate_select_queryKVPhân tích cú pháp và lập kế hoạch cho một SELECT duy nhất mà không thực thi. Trả về {valid, errors}. Chỉ SELECT; đúng một câu lệnh.sql
run_select_queryBảngThực thi một SELECT. Trả về {rows}. Chỉ đọc.sql, row_limit?
run_mutation_queryKVThực thi INSERT/UPDATE/REPLACE/DELETE đối với provider. Có tác dụng phụ thực sự. Trả về {messages, timestamp}. Được kiểm soát bởi chế độ máy chủ.sql
run_lifecycle_operationKVThực thi một thao tác vòng đời EXEC của stackql. Trả về {messages, timestamp}. Được kiểm soát bởi chế độ máy chủ.sql
list_registryBảngCác provider (và phiên bản của chúng) có trong registry đã cấu hình. Khác với list_providers, công cụ chỉ liệt kê các provider đã tải xuống.provider?
pull_providerKVCài đặt một provider từ registry vào bộ nhớ đệm cục bộ. Chỉ ảnh hưởng đến trạng thái bộ nhớ đệm cục bộ - không tác động đến mặt phẳng điều khiển hay mặt phẳng dữ liệu đám mây.provider, version?
reload_credentialsBảngNạp lại thông tin xác thực từ tệp dotenv --env.file vào môi trường tiến trình và báo cáo trạng thái phân giải theo từng provider (ok, unresolved, not_checked). Không bao giờ trả về giá trị bí mật. Được cho phép ở mọi chế độ.provider?

Tham khảo query_library_search trước khi tự viết SQL từ đầu, sau đó dùng query_library_get để xem xét một template phù hợp và tạo SQL từ template đó. Các công cụ truy vấn cũng chấp nhận source không bắt buộc chứa ID mục Query Library, chỉ dùng để ghi nhận nguồn; việc thực thi vẫn tuân theo chế độ máy chủ và chính sách phê duyệt thông thường.

ghi chú

describe_resource đã ngừng được hỗ trợ trong StackQL v0.12.732; các ứng dụng khách MCP, lời nhắc hoặc chỉ dẫn cho tác nhân từng gọi công cụ này nên gọi list_methods rồi đến describe_method thay thế. Một tài nguyên không có một danh sách trường duy nhất, vì mỗi phương thức truy cập trả về dạng riêng của nó, nên tên cột lấy từ describe_method cho phương thức mà truy vấn được định tuyến tới. Câu lệnh SQL DESCRIBE không thay đổi.

Các lời nhắc MCP hiện có​

Một lời nhắc tĩnh được công bố.

Lời nhắcMô tả
write_safe_selectHướng dẫn viết truy vấn SELECT an toàn đối với tài nguyên stackql. Giải thích cách dùng SHOW METHODS IN <provider>.<service>.<resource> để tìm phương thức đọc phù hợp và các tham số WHERE bắt buộc.

Cờ​

CờMô tả
--mcp.server.typeLoại máy chủ MCP: http, stdio hoặc reverse_proxy (loại sau cùng được dùng với stackql srv).
--mcp.configĐối tượng cấu hình JSON cho máy chủ MCP. YAML cũng được chấp nhận.
--mcp.protocol.versionBản sửa đổi giao thức mới nhất được công bố: auto (mặc định), 2026-07-28 hoặc một bản sửa đổi cũ hơn như 2025-11-25. Xem Ghim phiên bản sửa đổi.
--env.fileTệp thông tin xác thực kiểu dotenv được nạp khi khởi động và được công cụ reload_credentials nạp lại khi cần. Xem Nạp (lại) thông tin xác thực.
--pgsrv.portCổng TCP cho máy chủ giao thức wire của PostgreSQL (dùng với stackql srv).
-h, --helpIn thông tin trợ giúp.
-v, --verboseChạy ở chế độ chi tiết với đầu ra bổ sung.

   

xem Cờ toàn cục để biết thêm các tùy chọn

thông tin

Bạn cần đặt các biến môi trường cần thiết cho việc xác thực provider trước khi khởi động máy chủ MCP, hoặc chỉ định một tệp thông tin xác thực kiểu dotenv bằng --env.file. Để biết thêm thông tin, hãy xem Sử dụng provider.


Ví dụ​

Máy chủ MCP độc lập cơ bản​

Khởi chạy một máy chủ MCP độc lập với xác thực provider và một bearer token cho các ứng dụng khách của máy chủ:

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

Máy chủ MCP với máy chủ PostgreSQL (trong bộ nhớ)​

Chạy cả máy chủ MCP và máy chủ PostgreSQL để truy cập qua hai giao thức:

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

Máy chủ kiểm kê chỉ đọc ghi nhật ký kiểm tra vào một đường dẫn xác định​

Hữu ích cho một tác nhân quét kiểm kê không bao giờ được phép thay đổi dữ liệu:

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

Máy chủ tự động hóa có toàn quyền truy cập​

Dành cho các pipeline tự động hóa đáng tin cậy cần thực hiện thao tác thay đổi dữ liệu và không thể trả lời yêu cầu elicitation. Pipeline xuất trình bearer token được lưu trong 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"}}'

Máy chủ MCP bảo mật với TLS​

Khởi chạy một máy chủ MCP với mã hóa TLS ở chế độ reverse proxy:

Trước tiên, tạo chứng chỉ TLS (tự ký cho môi trường phát triển):

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

Sau đó khởi động máy chủ:

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

Kiểm thử máy chủ MCP của bạn​

Kho lưu trữ đi kèm một ứng dụng khách MCP dành cho phát triển (stackql_mcp_client) để viết tập lệnh và chạy kiểm thử hồi quy. Dựng ứng dụng khách này bằng:

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

Lệnh này tạo ra ./build/stackql_mcp_client.

Lưu ý rằng stackql_mcp_client không gửi header Authorization, vì vậy máy chủ mà nó nhắm tới phải đặt "allow_unauthenticated": true (như các ví dụ ở trên); máy chủ được bảo vệ bằng token sẽ trả lời nó bằng 401. Nó cũng không công bố khả năng elicitation của MCP - nó dành cho tập lệnh không tương tác. Với máy chủ safe, nó sẽ nhận lỗi từ chối "client does not support elicitation" đối với các lệnh gọi thay đổi dữ liệu và vòng đời; với máy chủ delete_safe, đối với các lệnh gọi DELETE và EXEC. Để kiểm thử tương tác với yêu cầu elicitation, hãy dùng một ứng dụng khách MCP nhúng trong trình soạn thảo (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 - succeeds only against a full_access server, or against
# delete_safe (for INSERT/UPDATE) or safe with an elicitation-capable client.
./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'"'"';"}'

Ví dụ phản hồi​

server_info (với máy chủ ở chế độ mặc định, StackQL v1.0.888 trên Windows qua 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 (với máy chủ full_access):

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

Ví dụ một dòng nhật ký kiểm tra cho cùng thao tác thay đổi dữ liệu đó:

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

Tích hợp với trợ lý AI​

Để tích hợp máy chủ MCP của StackQL với một trợ lý AI, hãy đăng ký stackql làm máy chủ MCP trong cấu hình của trợ lý. Hầu hết các ứng dụng khách MCP nhúng trong trình soạn thảo chạy máy chủ qua stdio; với các ứng dụng khách đó, dùng --mcp.server.type=stdio và trợ lý sẽ trực tiếp khởi chạy tiến trình. Các tác nhân độc lập dùng HTTP có thể kết nối tới một tiến trình stackql mcp --mcp.server.type=http chạy lâu dài.

Với Claude Desktop - bao gồm mục trong Anthropic Connector Directory (cách cài đặt được khuyên dùng), MCP Bundle có thể tải xuống (.mcpb) và cấu hình thủ công - hãy xem Sử dụng StackQL với Claude Desktop.

ghi chú

Vị trí tệp cấu hình khác nhau tùy theo hệ điều hành và trợ lý AI. Tham khảo tài liệu của trợ lý AI của bạn để biết đường dẫn và định dạng chính xác.


Cân nhắc về kiến trúc​

Khi chọn chế độ triển khai, hãy cân nhắc:

  1. Độc lập (stackql mcp): cách thiết lập đơn giản nhất, lý tưởng cho phát triển và cho các ứng dụng khách nhúng trong trình soạn thảo qua stdio.
  2. Hai máy chủ trong bộ nhớ (stackql srv với mcp.server.type=http): một tiến trình duy nhất phục vụ cả giao thức MCP và giao thức wire của PostgreSQL. Hiệu năng tốt nhất, phù hợp với hầu hết các triển khai trong môi trường sản xuất.
  3. Reverse proxy (stackql srv với mcp.server.type=reverse_proxy):
    • cho phép tách khối lượng công việc ra các tiến trình hoặc máy khác nhau
    • hỗ trợ mã hóa TLS cho điểm cuối MCP bảo mật
    • cho phép mở rộng quy mô độc lập cho giao diện MCP và giao diện PostgreSQL
    • mang lại sự linh hoạt cho việc tích hợp CA doanh nghiệp (lưu ý: hỗ trợ CA doanh nghiệp đang ở giai đoạn thử nghiệm)

Và riêng về an toàn:

  • Bắt đầu với mode: safe mặc định. Các ứng dụng khách MCP hỗ trợ elicitation (Claude Desktop, Cursor, Continue) sẽ hỏi người dùng trước mọi thao tác thay đổi dữ liệu.
  • Ghim mode: read_only cho các tác nhân kiểm kê hoặc phân tích không bao giờ được phép ghi.
  • Ghim mode: delete_safe khi bạn muốn tự do tạo/cập nhật nhưng vẫn muốn có con người tham gia quyết định đối với các thao tác phá hủy.
  • Chỉ dùng mode: full_access cho các pipeline tự động hóa đáng tin cậy, và chỉ khi kết hợp với một nhật ký kiểm tra có người xem xét.
  • Đặt server.auth_token_env_var trên mọi listener HTTP mà các tiến trình hoặc máy khác có thể truy cập; allow_unauthenticated dành cho phát triển cục bộ. Chỉ riêng TLS không xác thực được ứng dụng khách.
cẩn thận

Khi dùng TLS với các tổ chức phát hành chứng chỉ (CA) doanh nghiệp, có thể cần cấu hình bổ sung. Tính năng này đang ở giai đoạn thử nghiệm và có thể cần điều chỉnh tùy theo hệ thống CA cụ thể của bạn.


Đọc thêm​

  • Tài liệu tham khảo cho nhà phát triển gói là README của pkg/mcp_server trong kho lưu trữ stackql.
  • Tài liệu kỹ thuật dành cho người đóng góp nằm tại docs/mcp.md trong kho lưu trữ stackql và bao gồm ví dụ phản hồi cho mọi công cụ.