Skip to content

Security Guide

This document outlines security considerations and best practices for deploying and using the Natural Language Agent. Database credentials are configured when the MCP server starts via:

  • command-line options.
  • the configuration file (YAML format).
  • environment variables (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD).

You should never:

  • Commit .env files or credentials to version control.
  • Use .gitignore for configuration files that contain credentials (instead, exclude them entirely and use templates).
  • Hardcode security details in scripts.

You should instead:

  • Use environment variables in controlled environments (containers, orchestrators) for passing credentials at runtime.
  • Consider using secret management systems (Vault, AWS Secrets Manager, etc.) for production deployments.
  • Use a ~/.pgpass file or similar secure credential storage for local development.

Security Checklist

Pre-Deployment

  • Use strong passwords for database users.
  • Enable SSL/TLS for database connections.
  • Configure firewall rules.
  • Use read-only database user for queries.
  • Store credentials in environment variables or secrets manager.
  • Use HTTPS with valid certificates.
  • Set up API token authentication.
  • Configure token expiration.
  • Test in staging environment.

Production

  • Enable HTTPS with a valid CA certificate.
  • Enable authentication (do not use -no-auth).
  • Configure tokens with expiration dates.
  • Set private keys to 600 permissions.
  • Set token file to 600 permissions.
  • Set secret file to 600 permissions.
  • Back up secret file securely.
  • Run server as a non-root user.
  • Configure firewall rules.
  • Configure reverse proxy with rate limiting.
  • Configure monitoring and alerting.
  • Establish backup procedures.
  • Document incident response plan.
  • Schedule regular security audits.

Ongoing

  • Rotate API tokens quarterly.
  • Rotate database passwords quarterly.
  • Review access logs weekly.
  • Update certificates before expiration.
  • Review and update firewall rules.
  • Audit database user permissions.
  • Review token list for unused tokens.
  • Update software and dependencies.
  • Test backup and recovery procedures.
  • Conduct security training for team.

Security Monitoring Checklist

  • Set up log aggregation (ELK, Splunk, etc.).
  • Create alerts for authentication failures.
  • Monitor API token usage patterns.
  • Track database query patterns.
  • Set up intrusion detection (fail2ban, etc.).
  • Monitor certificate expiration.
  • Conduct regular token audits.
  • Review database user permissions.

Database Write Access

By default, all database connections operate in read-only mode. This is a critical safety feature that prevents the AI from accidentally or unintentionally modifying your data.

The allow_writes Setting

Each database connection can be configured with allow_writes: true to enable write operations. This setting should be used with extreme caution.

databases:
    - name: "development"
      host: "localhost"
      # ... other settings ...
      allow_writes: true  # DANGEROUS - enables data modifications

Risks of Enabling Write Access

When write access is enabled, the AI can execute:

  • INSERT - Add new data
  • UPDATE - Modify existing data
  • DELETE - Remove data
  • TRUNCATE - Empty entire tables
  • DROP - Delete tables, indexes, or other objects
  • ALTER - Modify table structures
  • Any other data-modifying SQL statements

Write Query Confirmation

The CLI and Web UI prompt for user confirmation before executing write queries on write-enabled databases. This safeguard applies to DDL statements (CREATE, DROP, ALTER, TRUNCATE) and DML statements (INSERT, UPDATE, DELETE).

The confirmation behavior differs by client:

  • The CLI displays the SQL query and prompts Execute this query? [y/N]: with No as the default.
  • The Web UI shows a dialog containing the SQL query with Cancel and Execute buttons.
  • Declining the query prevents execution and instructs the LLM not to retry the operation.
  • The server treats unknown query types as writes for safety.

Third-party MCP clients may also prompt for confirmation. The server sets destructiveHint: true and readOnlyHint: false annotations on the query_database tool when writes are enabled. These annotations follow the MCP specification and signal that the tool may modify data.

Recommendations

Never enable writes on production databases. Use read-only mode for production systems to prevent accidental data loss or corruption.

Only enable writes for:

  • Development/test databases with disposable data
  • Sandboxed environments isolated from production
  • Specific use cases where write operations are required and understood

Additional safeguards when using write access:

  • Use a dedicated database user with limited permissions
  • Enable database-level audit logging
  • Maintain regular backups
  • Consider using database snapshots before AI interactions
  • Monitor AI-generated queries for unexpected patterns

UI Indicators

When connected to a write-enabled database, the clients display warnings and require confirmation for write queries:

  • The Web client shows a prominent yellow warning banner and a confirmation dialog before executing write queries.
  • The CLI displays a [WRITE-ENABLED] marker, warning messages, and a confirmation prompt before write queries.
  • The allow_writes field in pg://system_info shows true for write-enabled connections.