How to Enable and Configure Bearer Token Authentication in the MCP Server Using Environment Variables

To enable Bearer token authentication in the MCP PostgreSQL Operations server, set REMOTE_AUTH_ENABLE=true and provide a secure REMOTE_SECRET_KEY when running the streamable-http transport.

The call518/mcp-postgresql-ops repository provides a FastMCP-based server that supports Bearer token authentication via environment variables when operating in HTTP mode. This configuration method allows you to externalize security settings from your codebase, making it ideal for containerized deployments and secret management systems.

Required Environment Variables

The server recognizes two specific environment variables that control authentication behavior for the HTTP transport.

REMOTE_AUTH_ENABLE

Set REMOTE_AUTH_ENABLE to activate Bearer token verification for incoming HTTP requests. The server accepts case-insensitive truthy values including true, 1, yes, or on. Any other value defaults to false, disabling authentication entirely.

When enabled, the server validates that REMOTE_SECRET_KEY is non-empty before startup. If the secret is missing, the server logs an error and aborts to prevent insecure configurations.

REMOTE_SECRET_KEY

Set REMOTE_SECRET_KEY to a non-empty string containing your Bearer token secret. The implementation recommends 32+ random characters for cryptographic strength. This value serves dual purposes: it acts as the valid Bearer token that clients must present in the Authorization header, and it generates the internal static token mapping for FastMCP.

Implementation Details in mcp_main.py

The authentication logic resides in src/mcp_postgresql_ops/mcp_main.py, where the server constructs a static token verifier before initializing the HTTP transport.

The function _build_static_token_auth(secret_key) (lines 73-80) creates a StaticTokenVerifier instance that maps your secret to a client identifier with read and write scopes. The server assigns this verifier to the global FastMCP instance via mcp.auth immediately before startup.

Environment variable parsing occurs in the argument resolution logic (lines 3694-3710). The code first checks for CLI flags (--auth-enable/--auth-disable), then falls back to REMOTE_AUTH_ENABLE using an internal _parse_bool_env helper. The REMOTE_SECRET_KEY variable is read similarly, though it can be overridden by the --secret-key CLI argument when provided.

Configuration Examples

Environment File Setup

Create a .env file in your project root following the reference in .env.example (lines 14-24):

# Transport configuration

FASTMCP_TYPE=streamable-http
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000

# Bearer token authentication

REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=MySuperSecretBearerKey12345

Store this file outside version control and inject it at runtime.

Docker Compose Configuration

When deploying via Docker Compose, pass the variables through the environment section:

services:
  mcp-server:
    image: call518/mcp-postgresql-ops:latest
    environment:
      - FASTMCP_TYPE=streamable-http
      - FASTMCP_HOST=0.0.0.0
      - FASTMCP_PORT=18003
      - REMOTE_AUTH_ENABLE=true
      - REMOTE_SECRET_KEY=${REMOTE_SECRET_KEY}
    ports:
      - "18003:18003"

This pulls the secret from your host environment or a separate .env file processed by Compose.

CLI Argument Overrides

You can override environment variables using CLI flags when starting the server directly:

mcp-postgresql-ops \
  --type streamable-http \
  --host 0.0.0.0 \
  --port 18003 \
  --auth-enable \
  --secret-key MySuperSecretBearerKey12345

The flags --auth-enable and --secret-key map to the same internal variables as their environment counterparts, allowing flexible deployment strategies.

Testing the Bearer Token

Validate your configuration by sending an authenticated request to the HTTP endpoint:

curl -H "Authorization: Bearer MySuperSecretBearerKey12345" \
     http://localhost:18003/api/v1/get-database-list

A missing or incorrect token triggers a 401 Unauthorized response from FastMCP's authentication middleware.

Summary

• Set REMOTE_AUTH_ENABLE=true to activate Bearer token authentication for the streamable-http transport.
• Provide a secure REMOTE_SECRET_KEY (32+ characters recommended) to serve as the valid Bearer token.
• The server aborts startup if authentication is enabled without a secret key, preventing insecure runtime states.
• Configuration is parsed in src/mcp_postgresql_ops/mcp_main.py (lines 3694-3710), with the static verifier constructed by _build_static_token_auth() (lines 73-80).
• Environment variables work seamlessly with Docker, Kubernetes, and CLI flag overrides.

Frequently Asked Questions

What happens if I enable authentication without setting a secret key?

The server detects the misconfiguration during startup validation and aborts with an error message. This safety mechanism prevents the server from running in an insecure state where authentication is enabled but any request could pass without a valid token.

Can I use CLI arguments instead of environment variables?

Yes. The server accepts --auth-enable/--auth-disable flags and a --secret-key argument that override environment variables when explicitly provided. However, environment variables remain the preferred method for production deployments using Docker or Kubernetes.

Is the Bearer token validation case-sensitive?

The token comparison performed by FastMCP's StaticTokenVerifier is exact and case-sensitive. You must present the REMOTE_SECRET_KEY value in the Authorization: Bearer <token> header with identical casing, though the REMOTE_AUTH_ENABLE environment variable itself accepts case-insensitive boolean values like True, TRUE, or true.

What scopes are assigned to authenticated requests?

The _build_static_token_auth() function assigns read and write scopes to the static token mapping by default. These scopes authorize the client to perform both query operations and database modifications through the MCP server endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}