Skip to main content

How to use StackQL with AI agents

StackQL ships a built-in Model Context Protocol (MCP) server. Any MCP-capable agent - Claude, Cursor, Continue, or a custom agent framework - connects to it and gains a self-describing, governed SQL interface to every cloud and SaaS provider in the StackQL registry.

Steps​

  1. Set provider credentials as environment variables before starting the server (the server inherits them):
export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY
  1. Start the MCP server. For a standalone HTTP server:
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912"}}'

For editor-embedded clients, use --mcp.server.type=stdio and let the client launch the process (see How to use StackQL with Claude). To serve MCP and the PostgreSQL wire protocol from one process, use stackql srv with the same MCP flags plus --pgsrv.port.

  1. Choose a safety mode. The mode is set in the server config and gates what agents can do:
ModeSELECT / metadataINSERT / UPDATEDELETEEXEC
read_onlyallowrefuserefuserefuse
safe (default)allowneeds approvalneeds approvalneeds approval
delete_safeallowallowneeds approvalneeds approval
full_accessallowallowallowallow

"Needs approval" uses the MCP elicitation flow: the client shows the user the pending SQL and the user accepts or declines. Pin read_only for inventory agents; reserve full_access for trusted pipelines with a reviewed audit log.

  1. Let the agent discover, then query. A typical agent session: server_info once, then list_providers -> list_methods (which reveals required WHERE parameters) -> validate_select_query -> run_select_query:
SELECT name, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

The agent never loads an SDK; the schema is discovered at runtime and the query is plain SQL.

Auditing​

Every tool call writes one JSONL record - timestamp, tool, mode, decision, query class, SQL, duration - to a file sink with rotation. Audit is on by default and records what the agent did (not result rows). In the default strict failure mode, a failed audit write surfaces as an error rather than letting an unaudited mutation slip through.