Security and access
MCP access
Give AI tools read-only access to StreamQL state and to a read-only SQL tool, with limits per token.
Overview#
StreamQL serves the Model Context Protocol on the admin port at /mcp over Streamable HTTP, never on the PostgreSQL data path. Access is by bearer token, shown once and stored as a SHA-256 digest. Every call is audited.
Enable it#
| Key | Default | Meaning |
|---|---|---|
mcp.enabled | false | Serve /mcp |
mcp.user, mcp.password | insights collector role | Login role for read-only SQL; each call switches to the token's own role |
mcp.max_connections | 4 | Concurrent database connections for all tokens |
mcp.max_rows_per_call | 10000 | Ceiling for every token's rows per call |
mcp.max_statement_timeout_ms | 30000 | Ceiling for every token's statement timeout |
mcp.max_result_bytes | 1048576 | Ceiling for result size |
mcp.lock_timeout_ms | 1000 | Lock timeout for read-only SQL |
mcp.allowed_hosts | empty | Accepted Host values. Empty accepts loopback and the host of access.public_url; ["*"] accepts any (a token is always required) |
mcp.allowed_origins | empty | Accepted browser Origin values; empty refuses requests that carry one |
mcp.audit_capacity | 500 | Recent calls kept for the console |
Tokens#
Create tokens in the console (MCP access, New token). A token has a name, access (read or operate), the databases it may reach, the tools it may call, optional sensitive resources (statement text, client addresses, audit log), an expiry and an optional IP allowlist. A token can never do more than the person who created it.
| Limit | Default | Meaning |
|---|---|---|
| Rows per call | 1000 | Rows a SQL call may return |
| Statement timeout | 5000 ms | Time one statement may run |
| Calls per minute | 30 | Rate limit |
| Database time per hour | 60000 ms | Rolling budget of database time |
Tools#
| Tool | Purpose |
|---|---|
list_databases, list_pools, pool_limits | Estate, pool and limit status |
list_clients | Live sessions; client addresses need the resource grant |
slow_queries, slow_query_detail, template_plan, list_hints | Slow-query templates, details, plans and hints |
capture_plan, update_hint | Operate access: queue a plan capture, change hint state |
read_audit_log | Needs the audit log resource |
query | Read-only SQL, run in a read-only transaction under the token's role; parameters are never returned |
Connect a client#
Clients that speak Streamable HTTP connect to https://your-host/mcp with the token in an Authorization: Bearer header. Clients that only launch local commands can use the stdio bridge, which reads the token from the environment:
export STREAMQL_MCP_TOKEN=... # the token shown once in the console
streamql mcp --url http://127.0.0.1:9930/mcp