Skip to main content

Documentation Index

Fetch the complete documentation index at: https://isthmus.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Options

OptionEnv varCLI flagTypeDefaultDescription
Database URLDATABASE_URL--database-urlstring(required)PostgreSQL connection string, e.g. postgres://user:pass@localhost:5432/mydb
Read onlyREAD_ONLY—booltrueWrap all queries in read-only transactions
Max rowsMAX_ROWS--max-rowsint100Maximum rows returned per query
Query timeoutQUERY_TIMEOUT--query-timeoutduration10sQuery execution timeout (Go duration format, e.g. 30s, 1m)
SchemasSCHEMAS—string(all non-system)Comma-separated list of schemas to expose, e.g. public,analytics
Policy filePOLICY_FILE--policy-filestring(none)Path to a policy YAML file for business context enrichment and column masking
Log levelLOG_LEVEL--log-levelstringinfoLog verbosity: debug, info, warn, error
Dry run—--dry-runboolfalseValidate config, connect to DB, ping, then exit
Explain only—--explain-onlyboolfalseForce all query calls to return EXPLAIN plans instead of results
TransportTRANSPORT--transportstringstdioTransport mode: stdio or http (docs)
HTTP addressHTTP_ADDR--http-addrstring:8080Listen address for HTTP transport, e.g. :3000, 127.0.0.1:8080
Bearer tokenHTTP_BEARER_TOKEN--http-bearer-tokenstring(required for HTTP)Bearer token for authenticating HTTP requests. See HTTP Transport
Audit log—--audit-logstring(none)Path to NDJSON file for query audit logging
OpenTelemetryOTEL_ENABLED--otelboolfalseEnable OpenTelemetry tracing and metrics (OTLP gRPC)
Version—--versionbool—Print version and exit

​
Connection pool

OptionEnv varCLI flagTypeDefaultDescription
Max connectionsPOOL_MAX_CONNS--pool-max-connsint5Maximum connections in the pool
Min connectionsPOOL_MIN_CONNS--pool-min-connsint1Minimum idle connections kept open
Max lifetimePOOL_MAX_CONN_LIFETIME--pool-max-conn-lifetimeduration30mMaximum 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.