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

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)

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"