> ## 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.

# Configuration

> All environment variables and CLI flags for configuring 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](/docs/features/policy-engine) for business context enrichment and [column masking](/docs/features/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](/docs/features/http-transport))                                                                 |
| HTTP address  | `HTTP_ADDR`         | `--http-addr`         | string   | `:8080`                 | Listen address for [HTTP transport](/docs/features/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](/docs/features/http-transport)                                        |
| Audit log     | —                   | `--audit-log`         | string   | *(none)*                | Path to NDJSON file for [query audit logging](/docs/features/audit-logging)                                                               |
| OpenTelemetry | `OTEL_ENABLED`      | `--otel`              | bool     | `false`                 | Enable [OpenTelemetry](/docs/features/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

```bash theme={null}
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:

```json theme={null}
{
  "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:

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

<Note>
  The source of truth for all configuration options is [`internal/config/config.go`](https://github.com/guillermoBallester/isthmus/blob/main/internal/config/config.go).
</Note>