Specifying your Configuration Preferences

You can provide your configuration preferences in multiple locations; the MCP server and Natural Language Agent give preference to options specified in the following order (highest to lowest):

1. Command line flags (highest priority)
2. Environment variables
3. Configuration file
4. Hard-coded defaults (lowest priority)

The server can read configuration preferences from a YAML file, making it easier to manage settings without environment variables. When configuring your MCP server and Natural Language Agent, keep your use and environment in mind:

• Development: Use environment variables or configuration files for easy iteration.
• Production: Use configuration files with command-line overrides for sensitive values.
• Claude Desktop: Use environment variables in the MCP configuration for simplicity.
• Secrets Management: Never commit API keys or passwords to version control.
• Connection Strings: Should use SSL/TLS in production (sslmode=require or sslmode=verify-full).

Specifying Properties in a Configuration File

By default, the configuration file is named postgres-mcp.yaml. The server searches for this file in /etc/pgedge/ first, then in the same directory as the binary. On the command line, you can use the -config flag to specify a different location.

A complete example configuration file with detailed comments is available here.

The following tables list the configuration options you can use to specify property values, grouped by section.

HTTP/HTTPS Server

Client Address Resolution

The server attributes each request to a client address, which it uses for login rate limiting and request logging. The http.client_ip settings control where that address comes from.

By default, the source is socket; the server takes the address from the network connection and ignores forwarding headers entirely. This default is correct for a server that clients reach directly, and a caller cannot influence it.

Deployments behind a reverse proxy see the proxy's address on every connection, so they need the real address from a forwarding header instead. Set the source to header and list the proxies you trust:

http:
  client_ip:
    source: header
    header: X-Real-IP
    trusted_proxies:
      - 192.0.2.10          # A single proxy address
      - 192.0.2.0/24        # Or a CIDR block

The server honours the header only when the connection comes from one of the listed proxies; a request that arrives from anywhere else is attributed to its own connection address. Starting the server with the source set to header and no trusted proxies configured is an error, because a forwarding header carries no authority unless the server knows which peer is entitled to set it.

X-Forwarded-For also works as the header, and the server handles it as the history list it is. Each proxy appends the address it received the request from, so the server reads the list from right to left, skipping entries that match trusted_proxies and taking the first one that does not. Reading from the left instead would return whatever the original caller chose to send, since anything a caller invents ends up at the far left of the list.

Database Connections

Each entry in the databases list supports the following options. See Multiple Database Configuration for details on configuring multiple databases and access control.

CLI flags and single-database environment variables (PGEDGE_DB_*, PG*) apply to the first database in the list. Use numbered environment variables (PGEDGE_DB_N_*) to configure multiple databases; see Environment Variables for details.

LLM Proxy

The LLM proxy is required for the web client in HTTP mode. The CLI client manages its own LLM connection and does not use these settings.

Embedding Generation

Knowledgebase

The knowledgebase embedding configuration is independent of the embedding section above.

Built-in Features

See Enabling or Disabling Built-in Features for details.

Other Options

Configuration Priority Examples

The following examples demonstrate how the MCP server's configuration priority works.

Example 1: Command Line Override

# Config file has: address: ":8080"
# Environment has: PGEDGE_HTTP_ENABLED="true"

./bin/pgedge-postgres-mcp \
  -http \
  -addr ":3000"

# Result:
# - HTTP enabled: true (from command line, highest priority)
# - Address: :3000 (from command line, highest priority)

Example 2: Environment Override

# Config file has: http.address: ":8080"
export PGEDGE_HTTP_ADDRESS=":9090"

./bin/pgedge-postgres-mcp

# Result:
# - Address: :9090 (environment overrides config file)

Example 3: Config File with Defaults

# No command line flags, no environment variables
# Config file has partial settings

./bin/pgedge-postgres-mcp -config myconfig.yaml

# Result:
# - Values from config file where present
# - Hard-coded defaults for missing values

Command Line Flags

Any configuration option specified in the configuration file can be overridden with a command line flag. Use the following command line options:

General Options:

• -config - Path to configuration file (default: same directory as binary)
• -debug - Enable debug logging (logs HTTP requests and responses)
• -trace-file - Path to JSONL trace file for debugging MCP interactions (disabled by default)

HTTP/HTTPS Options:

• -http - Enable HTTP transport mode
• -addr - HTTP server address (default: ":8080")
• -tls - Enable TLS/HTTPS (requires -http)
• -cert - Path to TLS certificate file
• -key - Path to TLS key file
• -chain - Path to TLS certificate chain file

Database Options:

• -db-host - Database host
• -db-port - Database port
• -db-name - Database name
• -db-user - Database user
• -db-password - Database password
• -db-sslmode - Database SSL mode (disable, require, verify-ca, verify-full)
• -db-sslcert - Path to the client certificate file, for client certificate authentication. Must be set together with -db-sslkey.
• -db-sslkey - Path to the client private key file, for client certificate authentication. Must be set together with -db-sslcert.
• -db-sslrootcert - Path to the CA certificate file used to verify the server. Takes effect only under -db-sslmode require, verify-ca, or verify-full; under disable, allow, or prefer (the default) the certificate is never checked against it and the value is silently ignored, matching libpq.
• -db-hosts - Comma-separated host:port pairs for multi-host failover (e.g., host1:5432,host2:5432)
• -db-target-session-attrs - Session routing attribute for multi-host connections (libpq default: any)

These flags apply to the first database in the configuration list.

Authentication Options:

• -no-auth - Disable API token authentication
• -token-file - Path to token file (default: {binary_dir}/postgres-mcp-tokens.yaml)
• -user-file - Path to user authentication file (default: {binary_dir}/postgres-mcp-users.yaml)

Token Management Options:

• -add-token - Add a new API token
• -remove-token - Remove token by ID or hash prefix
• -list-tokens - List all API tokens
• -token-note - Annotation for new token (with -add-token)
• -token-expiry - Token expiry duration: "30d", "1y", "2w", "12h", "never" (with -add-token)
• -token-database - Bind token to specific database name (with -add-token, empty = first configured database)

User Management Options:

• -add-user - Add a new user
• -update-user - Update an existing user
• -delete-user - Delete a user
• -list-users - List all users
• -enable-user - Enable a user account
• -disable-user - Disable a user account
• -username - Username for user management commands
• -password - Password for user management commands (prompted if not provided)
• -user-note - Annotation for the new user (with -add-user)

See Authentication Guide for details on token and user management.

Examples - Running the MCP Server

Starting the server in stdio mode with properties specified in a configuration file in the default location:

# Configure database connection via environment variables, config file, or flags
./bin/pgedge-postgres-mcp

The following example starts the MCP server in HTTP mode using properties specified on the command line and in a configuration file:

# Configure database connection via environment variables, config file, or flags
./bin/pgedge-postgres-mcp \
  -http \
  -addr ":9090"