Configuring the Server

The MCP server supports configuration through a YAML file, command-line flags, and environment variables.

The server applies configuration values in the following order from highest to lowest priority:

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

The server does not require a restart after every configuration change. Sending a SIGHUP signal reloads database connection, LLM proxy, and knowledgebase settings at runtime, without interrupting active connections. Authentication settings and HTTP server settings are exceptions; changes to either require a full restart to take effect, since these govern the listener and session state the server establishes at startup.

Reloading or Restarting the Server

If you have configured the server to use systemd, you can restart the service with systemctl to apply changes that require a full restart, such as authentication or HTTP server settings:

sudo systemctl restart pgedge-ai-dba-server

Without systemd, stop and relaunch the process manually:

pkill -f ai-dba-server
/opt/ai-workbench/ai-dba-server -config /etc/pgedge/ai-dba-server.yaml &

Docker Compose deployments use a dedicated restart subcommand instead; see Docker Deployment.

If you have made configuration changes that require only a reload, you can use a runtime configuration reload via SIGHUP to update the configuration:

kill -SIGHUP $(pgrep ai-dba-server)

A SIGHUP signal reloads the following settings:

• Database connection settings.
• LLM proxy settings.
• Knowledgebase settings.

Authentication settings and HTTP server settings require a full restart.

Specifying Server Options on the Command-Line

Command-line options take priority over environment variables and options specified in the configuration file. The following subsections group the flags by purpose:

• General Options
• HTTP Server Options
• Database Connection Options
• Token Management Options
• User Management Options
• Group Management Options
• Privilege Management Options
• Token Scope Options

General Options

The general options set the configuration file path, debug logging, the data directory, and the trace file.

HTTP Server Options

The HTTP server options configure the listen address and TLS certificate files for encrypted connections.

Database Connection Options

The database connection options set the host, port, credentials, and SSL mode for the PostgreSQL connection.

Token Management Options

Use the token management options to create, remove, list, and annotate service tokens.

User Management Options

The user management options add, update, delete, enable, and disable user and service accounts.

Group Management Options

The group management options create, delete, and list RBAC groups, and manage group membership and superuser status.

Privilege Management Options

The privilege management options grant, revoke, register, and list MCP privileges and connection access levels.

Token Scope Options

The token scope options set, clear, and display the connections and tools a service token can access.

Using Environment Variables to Specify Server Properties

The server reads environment variables at startup; those server properties specified in an environment variable are overridden by properties specified on the command line, but take precedence over properties written in a configuration file. The server supports the following variables:

• PGEDGE_POSTGRES_CONNECTION_STRING
• PGEDGE_DB_LOG_LEVEL
• PGEDGE_MEMORY_ENABLED

PGEDGE_POSTGRES_CONNECTION_STRING

The PGEDGE_POSTGRES_CONNECTION_STRING variable provides a PostgreSQL connection string for the datastore. The server uses this variable as a fallback when the configuration file does not specify database settings.

The server applies connection settings in the following priority order:

1. Database configuration from the YAML file or command-line flags.
2. The PGEDGE_POSTGRES_CONNECTION_STRING variable.
3. The default value postgres://localhost/postgres?sslmode=disable.

In the following example, the variable specifies a remote database:

export PGEDGE_POSTGRES_CONNECTION_STRING=\
"postgres://user:pass@db.example.com:5432/\
ai_workbench?sslmode=require"

PGEDGE_DB_LOG_LEVEL

The PGEDGE_DB_LOG_LEVEL variable controls the verbosity of database operation logging. The server writes database log messages to stderr with a [DATABASE] prefix.

The following values are supported:

• none disables all database logging (default).
• info logs connections, queries, and errors.
• debug logs metadata, pool details, and queries.
• trace logs full queries, row counts, and timings.

An empty or unrecognized value defaults to none.

In the following example, the variable enables debug logging:

export PGEDGE_DB_LOG_LEVEL=debug

PGEDGE_MEMORY_ENABLED

The PGEDGE_MEMORY_ENABLED variable controls the chat memory feature for Ask Ellie. The server reads this variable at startup and applies the value as an override to the memory.enabled configuration option.

The following values are supported:

• true enables chat memory (default).
• false disables chat memory.

In the following example, the variable disables chat memory:

export PGEDGE_MEMORY_ENABLED=false

Specifying Properties in a Configuration File

After applying command-line flags and environment variables, the server uses the configuration file to fill in any remaining settings. For details about the available server configuration options, see:

• HTTP Server (http) Properties
  • Using the cors_origin Property
• Connection Security (connection_security) Properties
• Database (database) Properties
• Embedding (embedding) Properties
• LLM Proxy (llm) Properties
  • Using the timeout_seconds Property
  • Using the compact_tool_descriptions Property
  • Using the openai_base_url Property
• Knowledgebase (knowledgebase) Properties
• Memory (memory) Properties
  • Using the Memory Tools (store_memory, recall_memories, delete_memory) Properties
• Built-in Features (builtins) Properties
• Paths and Directories
  • Using the data_dir Property
  • Using the trace_file Property

To review a sample file, see Configuration Examples.

The server searches for its configuration file in the following locations in the following order:

1. The absolute path specified via the -config flag.
2. The per-user config directory at ~/.config/pgedge/ai-dba-server.yaml on Linux (honouring $XDG_CONFIG_HOME), ~/Library/Application Support/pgedge/ai-dba-server.yaml on macOS, and %AppData%\pgedge\ai-dba-server.yaml on Windows.
3. System wide in /etc/pgedge/ai-dba-server.yaml.

HTTP Server Properties

The HTTP server properties configure the listener address, TLS certificates, and authentication rate limiting.

Using the cors_origin Property

The cors_origin option sets the value for the Access-Control-Allow-Origin response header. The empty default suits same-origin deployments, where the web client and the server share an origin. The server omits CORS headers entirely in that case.

Set cors_origin to an explicit origin when the web client runs on a different origin than the server. For example, use https://workbench.example.com as the value. The server returns Access-Control-Allow-Credentials: true so browsers can attach session cookies to cross-origin requests.

The server rejects a cors_origin value of "*" at startup when authentication is enabled. Browsers disallow combining Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true per the Fetch spec. Use an explicit origin, or leave the option empty for same-origin deployments.

In the following example, the http section allows cross-origin requests from a dedicated workbench host:

http:
  address: ":8443"
  cors_origin: "https://workbench.example.com"
  auth:
    enabled: true

Connection Security Properties

The connection security section controls SSRF protection for user-created database connections.

Database Properties

The database properties configure the PostgreSQL connection and connection pool for the server's datastore.

Embedding Properties

The provider option accepts voyage, openai, gemini, or ollama. The Gemini provider supports gemini-embedding-001 (the default, 3072 dimensions), gemini-embedding-2, and gemini-embedding-2-preview (also 3072 dimensions). Model availability varies by Gemini API key tier; run ListModels to verify which embedding models a given key can access.

LLM Proxy Properties

The LLM proxy is optional. When no valid API key is configured for the chosen provider, the server disables all AI features at startup. The web client detects the server's capabilities through the /api/v1/capabilities endpoint and hides all AI-dependent UI elements. The hidden elements include the AI Overview, Ask Ellie chat, alert analysis, chart analysis, and server analysis. The system continues to function as a monitoring tool without AI features.

For Ollama, a valid URL is sufficient because Ollama does not require an API key. For Anthropic, OpenAI, and Gemini, the corresponding API key file must contain a valid key.

Using the timeout_seconds Property

The timeout_seconds option sets the HTTP client timeout, in seconds, for every request the server makes to the configured LLM provider. The timeout applies uniformly to Anthropic, OpenAI, Gemini, and Ollama, including Ask Ellie chat requests. The default value is 120 seconds; values less than or equal to zero fall back to the default.

Increase this value when running local models on low-resource hardware or when full-context prompts regularly exceed the default; large prompts that combine schema, metrics, and connection data can take longer than 120 seconds on slow Ollama hosts. Raising the timeout to 300 prevents context deadline exceeded errors in these environments.

In the following example, the llm section extends the timeout for a slow local Ollama server:

llm:
  provider: "ollama"
  model: "llama3:latest"
  ollama_url: "http://localhost:11434"
  timeout_seconds: 300

Using the compact_tool_descriptions Property

The compact_tool_descriptions option controls whether the server sends compact or verbose tool descriptions to the LLM. The option accepts three values:

• auto (default) uses compact descriptions for localhost endpoints and verbose descriptions for remote APIs. Compact descriptions reduce prompt token count by approximately fifty-four percent.
• true always sends compact tool descriptions.
• false always sends verbose tool descriptions.

This setting affects the chat proxy (Ask Ellie) only. MCP protocol clients always receive full tool descriptions regardless of this setting.

In the following example, the llm section configures verbose tool descriptions:

llm:
  provider: "anthropic"
  model: "claude-sonnet-4-5"
  anthropic_api_key_file: "~/.anthropic-api-key"
  compact_tool_descriptions: "false"

Using the openai_base_url Property

The openai provider works with any server that implements the OpenAI-compatible API. Set openai_base_url to point at a local inference server. The API key is optional when using a custom base URL.

The following local inference servers are compatible:

• Docker Model Runner uses http://localhost:12434/engines/llama.cpp/v1 as the default endpoint.
• llama.cpp uses http://localhost:8080/v1 as the default endpoint.
• LM Studio uses http://localhost:1234/v1 as the default endpoint.
• EXO uses http://localhost:52415/v1 as the default endpoint.

In the following example, the llm section configures a local llama.cpp server:

llm:
  provider: "openai"
  model: "my-local-model"
  openai_base_url: "http://localhost:8080/v1"

Knowledgebase Properties

The embedding_provider option accepts voyage, openai, gemini, or ollama. The Gemini provider supports gemini-embedding-001 (the default, 3072 dimensions), gemini-embedding-2, and gemini-embedding-2-preview (also 3072 dimensions). Model availability varies by Gemini API key tier; run ListModels to verify which embedding models a given key can access.

When Gemini provides the knowledgebase embeddings, the configured embedding_model must match the model that the KB Builder used to produce the knowledgebase. The KB Builder uses gemini-embedding-001; selecting a different model produces incompatible embeddings and breaks similarity search.

Memory Properties

The memory section controls the chat memory feature for Ask Ellie. Chat memory allows Ellie to store and recall information across conversations.

The memory feature requires a configured PostgreSQL datastore connection. The server stores memories in the datastore alongside other persistent data. When memory is disabled, the three memory tools (store_memory, recall_memories, delete_memory) are unavailable even when enabled in the builtins.tools section.

Creating system-scoped memories requires the store_system_memory admin permission. Administrators assign this permission to groups through the admin panel. Users without the permission can only create user-scoped memories.

In the following example, the memory section disables chat memory:

memory:
  enabled: false

The PGEDGE_MEMORY_ENABLED environment variable can also control this setting; see Environment Variables for details.

Built-in Features Properties

The builtins section enables or disables individual tools and resources.

builtins:
  tools:
    query_database: true
    get_schema_info: true
    similarity_search: true
    execute_explain: true
    count_rows: true
    test_query: true
    list_probes: true
    describe_probe: true
    query_metrics: true
    list_connections: true
    get_alert_history: true
    get_alert_rules: true
    get_metric_baselines: true
    get_blackouts: true
    get_timeline_events: true
    query_datastore: true
    generate_embedding: true
    search_knowledgebase: true
    store_memory: true
    recall_memories: true
    delete_memory: true
  resources:
    system_info: true
    connection_info: true

Using the Memory Tool Properties

The memory tools (store_memory, recall_memories, delete_memory) allow Ellie to store and recall information across conversations. The server stores memories in the PostgreSQL datastore. When embedding generation is enabled, the recall_memories tool uses semantic similarity for searching. The tool falls back to text matching when embeddings are unavailable.

Set any memory tool to false in the builtins.tools section to disable the tool.

In the following example, the configuration disables the store_memory and delete_memory tools while keeping recall_memories enabled:

builtins:
  tools:
    store_memory: false
    delete_memory: false
    recall_memories: true

Paths and Directories

These properties configure filesystem paths for secrets, custom prompts, persistent data, and tracing.

Using the data_dir Property

The data_dir property specifies the location of persistent data files used for data storage:

• auth.db stores authentication data in a SQLite database.
• conversations.db stores chat history in a SQLite database.

The default location of the data files is ./data/ relative to the server binary.

In the following example, the -data-dir flag specifies a custom location:

./ai-dba-server -data-dir /var/lib/ai-workbench/data

The data directory can also be set in the configuration file:

data_dir: "/var/lib/ai-workbench/data"

Using the trace_file Property

You can use the trace_file property to instruct the server to log all MCP requests and responses to a trace file for debugging purposes.

In the following example, the -trace-file flag enables tracing:

./ai-dba-server \
    -trace-file /var/log/ai-workbench/mcp-trace.log

The trace file can also be set in the configuration file:

trace_file: "/var/log/ai-workbench/mcp-trace.log"

Configuration Examples

The examples that follow demonstrate how you might use server properties to configure your system. A complete sample configuration file is available at examples/ai-dba-server.yaml in the project repository.

#=====================================================
# HTTP SERVER CONFIGURATION
#=====================================================
http:
  # Address to listen on (host:port or :port)
  address: ":8080"

  # TLS/HTTPS Configuration
  tls:
    enabled: false
    # cert_file: "/etc/ai-workbench/certs/cert.pem"
    # key_file: "/etc/ai-workbench/certs/key.pem"
    # chain_file: "/etc/ai-workbench/certs/chain.pem"

  # Trusted reverse proxies (CIDR ranges)
  # trusted_proxies:
  #   - "10.0.0.0/8"
  #   - "172.16.0.0/12"

  # CORS origin for cross-origin deployments
  # cors_origin: "https://workbench.example.com"

  # Authentication Configuration
  auth:
    enabled: true
    max_failed_attempts_before_lockout: 0
    max_user_token_days: 0
    rate_limit_window_minutes: 15
    rate_limit_max_attempts: 10

#=====================================================
# CONNECTION SECURITY
#=====================================================
connection_security:
  allow_internal_networks: false
  # allowed_hosts:
  #   - "db.example.com"
  #   - "192.168.1.0/24"
  # blocked_hosts:
  #   - "169.254.169.254"

#=====================================================
# DATABASE CONNECTION
#=====================================================
database:
  host: "localhost"
  port: 5432
  database: "ai_workbench"
  user: "postgres"
  # password: ""
  # password_file: "/etc/pgedge/password.txt"
  sslmode: "prefer"
  pool_max_conns: 4
  pool_min_conns: 0
  pool_max_conn_idle_time: "30m"

#=====================================================
# EMBEDDING GENERATION
#=====================================================
embedding:
  enabled: false
  provider: "ollama"
  model: "nomic-embed-text"
  ollama_url: "http://localhost:11434"
  # voyage_api_key_file: "~/.voyage-api-key"
  # openai_api_key_file: "~/.openai-api-key"
  # gemini_api_key_file: "~/.gemini-api-key"

#=====================================================
# LLM CONFIGURATION (Web Client Chat Proxy)
#=====================================================
llm:
  provider: "anthropic"
  model: "claude-sonnet-4-5"
  # anthropic_api_key_file: "~/.anthropic-api-key"
  # openai_api_key_file: "~/.openai-api-key"
  # gemini_api_key_file: "~/.gemini-api-key"
  ollama_url: "http://localhost:11434"
  max_tokens: 4096
  temperature: 0.7
  max_iterations: 50
  compact_tool_descriptions: "auto"

#=====================================================
# KNOWLEDGEBASE CONFIGURATION
#=====================================================
knowledgebase:
  enabled: false
  # database_path: "/usr/share/pgedge/postgres-mcp-kb/kb.db"
  embedding_provider: "ollama"
  embedding_model: "nomic-embed-text"
  embedding_ollama_url: "http://localhost:11434"

#=====================================================
# CHAT MEMORY CONFIGURATION
#=====================================================
memory:
  enabled: true

#=====================================================
# BUILT-IN TOOLS, RESOURCES, AND PROMPTS
#=====================================================
builtins:
  tools:
    query_database: true
    get_schema_info: true
    similarity_search: true
    execute_explain: true
    count_rows: true
    test_query: true
    list_probes: true
    describe_probe: true
    query_metrics: true
    list_connections: true
    get_alert_history: true
    get_alert_rules: true
    get_metric_baselines: true
    get_blackouts: true
    get_timeline_events: true
    query_datastore: true
    generate_embedding: true
    search_knowledgebase: true
    store_memory: true
    recall_memories: true
    delete_memory: true
  resources:
    system_info: true
    connection_info: true

#=====================================================
# PATHS AND DATA DIRECTORIES
#=====================================================
# secret_file: "/etc/ai-workbench/server.secret"
# custom_definitions_path: "/etc/ai-workbench/defs.yaml"
# data_dir: "/var/lib/ai-workbench/data"

Sample: Development Configuration

http:
  address: ":8080"
  tls:
    enabled: false
  auth:
    enabled: true
connection_security:
  allow_internal_networks: true
database:
  host: "localhost"
  port: 5432
  database: "ai_workbench"
  user: "postgres"
  sslmode: "disable"
embedding:
  enabled: true
  provider: "ollama"
  model: "nomic-embed-text"
llm:
  provider: "ollama"
  model: "llama3:latest"

Sample: Production Configuration

http:
  address: ":8443"
  tls:
    enabled: true
    cert_file: "/etc/ai-workbench/certs/cert.pem"
    key_file: "/etc/ai-workbench/certs/key.pem"
  trusted_proxies:
    - "10.0.0.0/8"
    - "172.16.0.0/12"
  cors_origin: "https://workbench.example.com"
  auth:
    enabled: true
    max_failed_attempts_before_lockout: 5
    max_user_token_days: 90
connection_security:
  allow_internal_networks: false
  allowed_hosts:
    - "db.internal.example.com"
  blocked_hosts:
    - "169.254.169.254"
database:
  host: "db.internal.example.com"
  port: 5432
  database: "ai_workbench_prod"
  user: "ai_workbench"
  sslmode: "verify-full"
  pool_max_conns: 10
embedding:
  enabled: true
  provider: "voyage"
  model: "voyage-3"
  voyage_api_key_file: "/etc/ai-workbench/voyage-key"
llm:
  provider: "anthropic"
  model: "claude-sonnet-4-5"
  anthropic_api_key_file: "/etc/ai-workbench/ant-key"
secret_file: "/etc/ai-workbench/server.secret"
data_dir: "/var/lib/ai-workbench/data"