Configuration - Isthmus

Isthmus is configured via environment variables, with optional CLI flag overrides. The precedence order is: CLI flags > Environment variables > Defaults

Options

Option	Env var	CLI flag	Type	Default	Description
Database URL	`DATABASE_URL`	`--database-url`	string	(required)	PostgreSQL connection string, e.g. `postgres://user:pass@localhost:5432/mydb`
Read only	`READ_ONLY`	—	bool	`true`	Wrap all queries in read-only transactions
Max rows	`MAX_ROWS`	`--max-rows`	int	`100`	Maximum rows returned per query
Query timeout	`QUERY_TIMEOUT`	`--query-timeout`	duration	`10s`	Query execution timeout (Go duration format, e.g. `30s`, `1m`)
Schemas	`SCHEMAS`	—	string	(all non-system)	Comma-separated list of schemas to expose, e.g. `public,analytics`
Policy file	`POLICY_FILE`	`--policy-file`	string	(none)	Path to a policy YAML file for business context enrichment and column masking
Log level	`LOG_LEVEL`	`--log-level`	string	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
Dry run	—	`--dry-run`	bool	`false`	Validate config, connect to DB, ping, then exit
Explain only	—	`--explain-only`	bool	`false`	Force all `query` calls to return EXPLAIN plans instead of results
Transport	`TRANSPORT`	`--transport`	string	`stdio`	Transport mode: `stdio` or `http` (docs)
HTTP address	`HTTP_ADDR`	`--http-addr`	string	`:8080`	Listen address for HTTP transport, e.g. `:3000`, `127.0.0.1:8080`
Bearer token	`HTTP_BEARER_TOKEN`	`--http-bearer-token`	string	(required for HTTP)	Bearer token for authenticating HTTP requests. See HTTP Transport
Audit log	—	`--audit-log`	string	(none)	Path to NDJSON file for query audit logging
OpenTelemetry	`OTEL_ENABLED`	`--otel`	bool	`false`	Enable OpenTelemetry tracing and metrics (OTLP gRPC)
Version	—	`--version`	bool	—	Print version and exit

Connection pool

Option	Env var	CLI flag	Type	Default	Description
Max connections	`POOL_MAX_CONNS`	`--pool-max-conns`	int	`5`	Maximum connections in the pool
Min connections	`POOL_MIN_CONNS`	`--pool-min-conns`	int	`1`	Minimum idle connections kept open
Max lifetime	`POOL_MAX_CONN_LIFETIME`	`--pool-max-conn-lifetime`	duration	`30m`	Maximum lifetime of a connection before it is closed and replaced

Pool settings rarely need tuning. The defaults are appropriate for a single-user local MCP server. Increase POOL_MAX_CONNS if you serve multiple concurrent clients over HTTP transport.

Example .env file

DATABASE_URL=postgres://readonly:secret@localhost:5432/production
MAX_ROWS=500
QUERY_TIMEOUT=30s
SCHEMAS=public,analytics
POLICY_FILE=./policy.yaml
LOG_LEVEL=info

# HTTP transport (uncomment to serve over HTTP instead of stdio)
# TRANSPORT=http
# HTTP_ADDR=:8080
# HTTP_BEARER_TOKEN=your-secret-token-here

# Observability (uncomment to enable)
# OTEL_ENABLED=true

# Connection pool tuning (defaults are fine for most use cases)
# POOL_MAX_CONNS=5
# POOL_MIN_CONNS=1
# POOL_MAX_CONN_LIFETIME=30m

MCP client configuration

When using Isthmus with an MCP client, environment variables are passed in the client’s config file. For example, in Claude Desktop:

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "env": {
        "DATABASE_URL": "postgres://readonly:secret@localhost:5432/production",
        "MAX_ROWS": "500",
        "SCHEMAS": "public,analytics",
        "POLICY_FILE": "/path/to/policy.yaml"
      }
    }
  }
}

CLI flags can be passed via the args array:

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "args": ["--audit-log", "/tmp/isthmus-audit.ndjson", "--explain-only"],
      "env": {
        "DATABASE_URL": "postgres://readonly:secret@localhost:5432/production"
      }
    }
  }
}

The source of truth for all configuration options is internal/config/config.go.