Skip to main content
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:
Store in database, with each configuration as a record. Currently supports three databases: SQLite3, PostgreSQL, MySQL
Store configurations through API endpoints, allowing for external configuration management systems
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, api
  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

  # API configuration (used when type is 'api')
  api:
    url: "${GATEWAY_STORAGE_API_URL:}"                  # API endpoint URL
    configJSONPath: "${GATEWAY_STORAGE_API_CONFIG_JSON_PATH:}"  # JSON path for config in API response
    timeout: "${GATEWAY_STORAGE_API_TIMEOUT:30s}"       # Request timeout

​
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!

​
OAuth Login Configuration

OAuth configuration enables third-party login functionality, currently supporting Google and GitHub login. When the corresponding client_id and client_secret are configured, the web interface will automatically enable OAuth login options. 
oauth:
  # Google OAuth Configuration
  google:
    client_id: "${OAUTH_GOOGLE_CLIENT_ID:}"                    # Google OAuth Client ID
    client_secret: "${OAUTH_GOOGLE_CLIENT_SECRET:}"            # Google OAuth Client Secret

  # GitHub OAuth Configuration
  github:
    client_id: "${OAUTH_GITHUB_CLIENT_ID:}"                    # GitHub OAuth Client ID
    client_secret: "${OAUTH_GITHUB_CLIENT_SECRET:}"            # GitHub OAuth Client Secret

Google Login

Supports Google account login, requires OAuth app configuration in Google Cloud Console

GitHub Login

Supports GitHub account login, requires creating an OAuth app in GitHub
  • OAuth login options are only enabled when the corresponding client_id and client_secret are configured
  • OAuth login can be used alongside local account login
  • Users logging in via OAuth for the first time will have accounts created automatically

​
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.
⌘I