# srv

> The stackql srv command runs StackQL as a PostgreSQL wire protocol server, so psql, BI tools and language drivers can query cloud and SaaS APIs with SQL.

Source: https://stackql.io/command-line-usage/srv

Command used to launch StackQL as a service, which can then be accessed by clients using [Postgres wire protocol](https://www.postgresql.org/docs/current/protocol.html) clients authenticated using mTLS. The `srv` command can also run a [Model Context Protocol (MCP)](/command-line-usage/mcp) server alongside the PostgreSQL wire protocol server, enabling dual-protocol access for both traditional database clients and AI agents.

* * * 

### Syntax

`stackql srv [server_options] [flags]`

* * *

:::note

Although the StackQL server uses the Postgres wire protocol, it is not a Postgres server, nor does it require one.  The wire protocol is used by the client to communicate with the server which uses StackQL to perform queries or DML operations against remote cloud and SaaS providers and return results back to the client.

:::

Parameters sent over the extended query protocol (`Parse` / `Bind` / `Execute`, as used by `psycopg` 3, `pgx` and JDBC) are bound server side as string literals.  From `v0.12.742` a `$n` placeholder inside a string literal, quoted identifier or comment is left alone, backslashes in parameter values are escaped, and a text value of `NULL` stays the string `NULL` (SQL `NULL` is carried separately).

### Server Options

| Option | Description |
|--|--|
|`--pgsrv.address`|Address the server is listening on (typically `0.0.0.0`)|
|`--pgsrv.port`|Port the server is listening on (e.g. `5444`)|
|`--pgsrv.tls`|mTLS configuration object, see the [example](#examples) below|
|`--pgsrv.loglevel`|Log level (default `WARN`)|

> see [Global Flags](/command-line-usage/global-flags) for additional options

### MCP Server Options

When running the `srv` command with MCP support, the following additional options are available:

| Option | Description |
|--|--|
|`--mcp.server.type`|MCP server type: `http` (in-memory) or `reverse_proxy` (TCP-based)|
|`--mcp.config`|JSON configuration object for the MCP server (see [MCP documentation](/command-line-usage/mcp))|
|`--mcp.log.format`|MCP audit log encoding: `jsonl` (default) or `otel` (OTLP/JSON log records); overrides `server.audit.format` in the configuration object|
|`--mcp.protocol.version`|Newest MCP protocol revision advertised: `auto` (default), `2026-07-28` (sessionless only) or an older revision such as `2025-11-25`; overrides `server.protocol_version` in the configuration object|

:::info[Breaking change in v0.12.742]

From `v0.12.742` the MCP HTTP transport (`--mcp.server.type=http` or `reverse_proxy`) refuses to start unless the configuration object names a bearer token with `server.auth_token_env_var` or opts out explicitly with `"allow_unauthenticated": true`.  See [HTTP client authentication](/command-line-usage/mcp#http-client-authentication).

:::

:::tip

See the [MCP command documentation](/command-line-usage/mcp) for detailed information on configuring and using the MCP server, including deployment modes, configuration options, and integration with AI assistants.

:::

:::info

You need to set environment variables required for provider authentication before starting the server, see [Using a Provider](/getting-started/using-a-provider) for more information.

:::

For long-running servers, the [`--env.file`](/command-line-usage/global-flags) flag lets you lay down or rotate credentials in a dotenv-style file on disk before startup rather than exporting variables into the shell:

```bash
stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env
```

For `stackql srv` the file is read once at startup; the mid-session re-source path is the MCP [`reload_credentials`](/mcp/reload_credentials) tool.

### Flags

| Flag | Description |
|--|--|
|`-H,--help`|Print help information|
|`-v,--verbose`|Run queries in verbose mode with additional output sent to stdout, if the `-f` option is selected this additional logging information will be written to the output file along with the query results|

> see [Global Flags](/command-line-usage/global-flags) for additional options

* * *

### Examples

Launch a StackQL server process and connect using a `psql` command line client.  

First download the `openssl.cnf` configuration file from [stackql/stackql](https://raw.githubusercontent.com/stackql/stackql/main/test/server/mtls/openssl.cnf).  

Next generate the certificate and key files to be used by the server and client for mutual TLS authentication (mTLS).  

```bash
openssl req -x509 -keyout ~/stackqlcreds/server_key.pem -out ~/stackqlcreds/server_cert.pem -config ./openssl.cnf -days 365
openssl req -x509 -keyout ~/stackqlcreds/client_key.pem -out ~/stackqlcreds/client_cert.pem -config ./openssl.cnf -days 365
chmod 400 ~/stackqlcreds/client_key.pem
```

Now set environment variables, if the client and server are on the same host, these can be shared.  

```bash
export PGPORT=5444
export PGSSLCERT=~/stackqlcreds/client_cert.pem
export PGSSLKEY=~/stackqlcreds/client_key.pem
export PGSSLROOTCERT=~/stackqlcreds/server_cert.pem
export PGSSLSRVKEY=~/stackqlcreds/server_key.pem
export CLIENT_CERT=$(base64 -w 0 ~/stackqlcreds/client_cert.pem)
export PGSSLMODE=allow
```

Set up an authentication object for whatever providers the server will need access to, for instance for GitHub.  

```bash
export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken
```

Now start the server in one terminal.  

```bash
stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'
```

In another terminal, connect to the server using the `psql` command line client.  

```bash
psql 127.0.0.1
```

Now run a StackQL query against an authenticated provider.  

```
psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.

127.0.0.1=> SHOW SERVICES IN github LIKE '%repos%';
      id      | name  |           title
--------------+-------+----------------------------
 repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)

127.0.0.1=>
```