The configuration file supports environment variable injection using the ${VAR:default} syntax. If an environment variable is not set, the default value will be used.

A common practice is to inject values through different .env, .env.development, .env.prod files, though you can also directly modify the configuration with hardcoded values.

​
Logging Configuration

Logging configuration controls the application’s log output behavior:

logger:
  level: "${APISERVER_LOGGER_LEVEL:info}"                                         # Log level: debug, info, warn, error
  format: "${APISERVER_LOGGER_FORMAT:console}"                                    # Log format: json, console
  output: "${APISERVER_LOGGER_OUTPUT:stdout}"                                     # Output method: stdout, file
  file_path: "${APISERVER_LOGGER_FILE_PATH:/var/log/unla/apiserver.log}"          # Log file path (when output is file)
  max_size: ${APISERVER_LOGGER_MAX_SIZE:100}                                      # Maximum log file size (MB)
  max_backups: ${APISERVER_LOGGER_MAX_BACKUPS:3}                                  # Number of backup files to retain
  max_age: ${APISERVER_LOGGER_MAX_AGE:7}                                          # Backup file retention days
  compress: ${APISERVER_LOGGER_COMPRESS:true}                                     # Whether to compress backup files
  color: ${APISERVER_LOGGER_COLOR:true}                                           # Whether to use colors in console output
  stacktrace: ${APISERVER_LOGGER_STACKTRACE:true}                                 # Whether error logs include stack traces

Log Levels

Supports four levels: debug, info, warn, error

Output Format

Supports JSON structured output and console readable format

File Rotation

Automatically manages log file size and quantity

Stack Trace

Error logs can include detailed call stack information

​
Internationalization Configuration

Internationalization configuration is used to support multi-language interfaces:

i18n:
  path: "${APISERVER_I18N_PATH:/etc/unla/i18n}"                                   # Translation file path

The translation file path should contain translation files for various languages to support multi-language user interfaces.

​
Chat Message Database Configuration

This configuration mainly targets the backend chat message storage configuration (of course, this can be stored in the same database as the proxy configuration), primarily used to store chat sessions and message data from the Web interface.

The chat message database is mainly used to store MCP chat records conducted through the Web interface, and is separate from the gateway proxy configuration storage.

​
Supported Databases

Currently supports 3 types of databases:

SQLite3

Suitable for development environments and small-scale deployments

PostgreSQL

Recommended for production environments

MySQL

Traditional relational database choice

​
Configuration Example

database:
  type: "${APISERVER_DB_TYPE:sqlite}"               # Database type (sqlite, postgres, mysql)
  host: "${APISERVER_DB_HOST:localhost}"            # Database host address
  port: ${APISERVER_DB_PORT:5432}                   # Database port
  user: "${APISERVER_DB_USER:postgres}"             # Database username
  password: "${APISERVER_DB_PASSWORD:example}"      # Database password
  dbname: "${APISERVER_DB_NAME:./unla.db}"          # Database name or file path
  sslmode: "${APISERVER_DB_SSL_MODE:disable}"       # SSL mode for database connection

If you need additional database support, you can request it in the Issues, or you can directly implement the corresponding impl and submit a PR :)

​
Gateway Proxy Storage Configuration

This is used to store gateway proxy configurations, which corresponds to the configuration that maps from MCP to API.

Currently supports 2 storage methods:

The revision_history_limit parameter controls the number of configuration version histories retained by the system, which helps with configuration rollback and auditing. The default is to retain 10 versions.

​
Configuration Example

storage:
  type: "${GATEWAY_STORAGE_TYPE:db}"                                      # Storage type: db, disk
  revision_history_limit: ${GATEWAY_STORAGE_REVISION_HISTORY_LIMIT:10}    # Number of version histories to retain

  # Database configuration (used when type is 'db')
  database:
    type: "${GATEWAY_DB_TYPE:sqlite}"                   # Database type (sqlite, postgres, mysql)
    host: "${GATEWAY_DB_HOST:localhost}"                # Database host address
    port: ${GATEWAY_DB_PORT:5432}                       # Database port
    user: "${GATEWAY_DB_USER:postgres}"                 # Database username
    password: "${GATEWAY_DB_PASSWORD:example}"          # Database password
    dbname: "${GATEWAY_DB_NAME:./unla.db}"              # Database name or file path
    sslmode: "${GATEWAY_DB_SSL_MODE:disable}"           # SSL mode for database connection

  # Disk configuration (used when type is 'disk')
  disk:
    path: "${GATEWAY_STORAGE_DISK_PATH:}"               # Data file storage path

​
Notification Configuration

The notification configuration module is mainly used to let mcp-gateway sense updates and perform hot reloading without restarting the service when configuration is updated.

​
Supported Notification Methods

signal

Notify by sending operating system signals, similar to kill -SIGHUP <pid> or nginx -s reload

api

Notify by calling an API, mcp-gateway will listen on a separate port

redis

Notify through Redis publish/subscribe functionality, suitable for single-machine or cluster deployments

composite

Composite notification using multiple methods, signal and api are always enabled by default

​
Notification Roles

1

sender

Sender, responsible for sending notifications, apiserver can only use this mode

2

receiver

Receiver, responsible for receiving notifications, single-machine mcp-gateway should only use this mode

3

both

Both sender and receiver, cluster-deployed mcp-gateway can use this method

​
Configuration Example

notifier:
  role: "${APISERVER_NOTIFIER_ROLE:sender}"  # Role: 'sender' or 'receiver'
  type: "${APISERVER_NOTIFIER_TYPE:signal}"  # Type: 'signal', 'api', 'redis' or 'composite'

  # Signal configuration (used when type is 'signal')
  signal:
    signal: "${APISERVER_NOTIFIER_SIGNAL:SIGHUP}"                       # Signal to send
    pid: "${APISERVER_NOTIFIER_SIGNAL_PID:/var/run/mcp-gateway.pid}"    # PID file path

  # API configuration (used when type is 'api')
  api:
    port: ${APISERVER_NOTIFIER_API_PORT:5235}                                           # API port
    target_url: "${APISERVER_NOTIFIER_API_TARGET_URL:http://localhost:5235/_reload}"    # Reload endpoint

  # Redis configuration (used when type is 'redis')
  redis:
    addr: "${APISERVER_NOTIFIER_REDIS_ADDR:localhost:6379}"                             # Redis address
    password: "${APISERVER_NOTIFIER_REDIS_PASSWORD:UseStrongPasswordIsAGoodPractice}"   # Redis password
    db: ${APISERVER_NOTIFIER_REDIS_DB:0}                                                # Redis database number
    topic: "${APISERVER_NOTIFIER_REDIS_TOPIC:mcp-gateway:reload}"                       # Redis publish/subscribe topic

​
Super Administrator Configuration

Super administrator configuration is used to set up the system’s initial administrator account. Each time apiserver starts, it will automatically detect if it exists, and if not, it will be created automatically.

super_admin:
  username: "${SUPER_ADMIN_USERNAME:admin}"                                     # Super administrator username
  password: "${SUPER_ADMIN_PASSWORD:changeme-please-use-a-secure-password}"     # Super administrator password (please change in production)

Strongly recommend using strong passwords in production or public network environments!

​
JWT Configuration

JWT configuration is used to set web authentication related parameters:

jwt:
  secret_key: "${APISERVER_JWT_SECRET_KEY:changeme-please-generate-a-random-secret}"  # JWT secret key (please change in production)
  duration: "${APISERVER_JWT_DURATION:24h}"                                           # Token validity period

Strongly recommend using strong passwords in production or public network environments!

​
Configuration File Location

By default, the configuration file should be placed in the following locations:

  • Container deployment: /app/configs/apiserver.yaml
  • Binary deployment: ./configs/apiserver.yaml

You can specify a custom configuration file path through environment variables or command line parameters.