Configuration Options

This document provides an overview of how to configure the mcp-server-trento using command-line parameters, configuration files, and environment variables.

Configuration Sources

The mcp-server-trento supports multiple configuration sources with the following priority order (highest to lowest):

  1. Command-line flags - Override all other settings

  2. Environment variables - Useful for containerized deployments

  3. Configuration file - YAML file for persistent settings

  4. Built-in defaults - Fallback values

Configuration File

You can create a mcp-server-trento file in the working directory or specify a custom path using the --config flag.

The Trento MCP Server searches for configuration files in the following order:

  1. System-wide directory (/etc/trento/mcp-server-trento or /usr/etc/trento/agent.yaml)

  2. Custom path specified with --config flag

## Custom paths for API autodiscovery endpoints (comma-separated), used when OAS_PATH is empty and TRENTO_URL is set.
AUTODISCOVERY_PATHS=/api/all/openapi,/wanda/api/all/openapi

## Enable the health check server.
ENABLE_HEALTH_CHECK=false

## The HTTP header name used to pass the Trento API key for authentication with the Trento server.
HEADER_NAME=X-TRENTO-MCP-APIKEY

## The API path used for health checks on target servers.
HEALTH_API_PATH=/api/healthz

## The port on which the health check server listens for incoming connections.
HEALTH_PORT=8080

## List of comma-separated paths to the OpenAPI specification files (local or remote URLs).
## If not provided, the server will attempt autodiscovery using the Trento URL and autodiscovery paths.
OAS_PATH=http://localhost:4000/api/all/openapi,http://localhost:4001/wanda/api/all/openapi

## The port on which the MCP Server listens for incoming connections.
PORT=5000

## List of OpenAPI tags to filter which operations are exposed as MCP tools. Only operations with at least one matching tag will be available.
TAG_FILTER=MCP

## The transport protocol to use for MCP communication. Options: 'streamable' (default) or 'sse'.
TRANSPORT=streamable

## Target Trento server, useful when targeting remote Trento servers. Empty by default.
TRENTO_URL=

##  The logging verbosity level. Options: 'debug', 'info', 'warning', 'error'.
VERBOSITY=info

System-Wide Configuration

For system-wide configuration, place the config file in /etc/trento/mcp-server-trento:

sudo mkdir -p /etc/trento
sudo tee /etc/trento/mcp-server-trento > /dev/null <<EOF
TRENTO_URL=https://prod.trento.io
EOF

Then run the server:

mcp-server-trento

Environment Variables

All command-line flags can also be set via environment variables. The environment variable name is constructed by adding the TRENTO_MCP_ prefix to the configuration key (e.g., TRENTO_MCP_PORT).

For slice values like TRENTO_MCP_OAS_PATH and TRENTO_MCP_TAG_FILTER, provide a comma-separated string.

Command-Line Parameters

The mcp-server-trento binary accepts several command-line flags to configure its behavior. The following table lists all available configuration options, their corresponding flags, environment variables, and default values.

Flag & Config Key Environment Variable Default Value Description

--autodiscovery-paths, -A

TRENTO_MCP_AUTODISCOVERY_PATHS

/api/all/openapi,/wanda/api/all/openapi

Custom paths for API autodiscovery.

--config, -c

TRENTO_MCP_CONFIG

(empty)

Config file path.

--enable-health-check, -d

TRENTO_MCP_ENABLE_HEALTH_CHECK

false

Enable the health check server.

--header-name, -H

TRENTO_MCP_HEADER_NAME

X-TRENTO-MCP-APIKEY

The header name to be used for the passing the Trento API key to the MCP server.

--health-api-path, -a

TRENTO_MCP_HEALTH_API_PATH

/api/healthz

The API path used for health checks on target servers.

--health-port, -z

TRENTO_MCP_HEALTH_PORT

8080

The port on which to run the health check servers, like Trento Web or Wanda.

--insecure-skip-tls-verify, -i

TRENTO_MCP_INSECURE_SKIP_TLS_VERIFY

false

Skip TLS certificate verification when fetching OpenAPI spec from HTTPS URLs.

--oas-path, -P

TRENTO_MCP_OAS_PATH

[]

Path to the OpenAPI spec file(s). Can be specified multiple times.

--port, -p

TRENTO_MCP_PORT

5000

The port on which to run the MCP server.

--tag-filter, -f

TRENTO_MCP_TAG_FILTER

["MCP"]

Only include operations with at least one of these tags. If empty, all operations are included.

--transport, -t

TRENTO_MCP_TRANSPORT

streamable

The protocol to use, choose "streamable" or "sse".

--trento-url, -u

TRENTO_MCP_TRENTO_URL

(empty)

URL for the target Trento server. Required for autodiscovery if oas-path is not set.

--verbosity, -v

TRENTO_MCP_VERBOSITY

info

Log level verbosity (debug, info, warning, error).

Configuration Examples

Using Configuration File Only

# Create mcp-server-trento with your settings
mcp-server-trento

Using Environment Variables

export TRENTO_MCP_PORT=5000
export TRENTO_MCP_TRENTO_URL=https://prod.trento.io
export TRENTO_MCP_VERBOSITY=debug
mcp-server-trento

Using Command-Line Flags (Override Everything)

# Basic usage
mcp-server-trento --port 9000 --verbosity debug --trento-url https://test.trento.io

# Multiple OpenAPI specifications
mcp-server-trento --oas-path https://api1.example.com/openapi.json --oas-path https://api2.example.com/openapi.json

# With autodiscovery using custom paths
mcp-server-trento --trento-url https://trento.example.com --autodiscovery-paths /api/v1/openapi,/wanda/api/v1/openapi

# With health checks enabled
mcp-server-trento --enable-health-check --health-port 8080 --port 5000

Mixed Configuration

# Set base config via environment
export TRENTO_MCP_PORT=5000
export TRENTO_MCP_VERBOSITY=info

# Override specific values via flags
mcp-server-trento --port 9000 --config /etc/trento/mcp-server-trento
# Result: port=9000 (from flag), verbosity=info (from env), other settings from config file

Docker Container Example

# Basic container without health checks
docker run -p 5000:5000 \
  -e TRENTO_MCP_PORT=5000 \
  -e TRENTO_MCP_TRENTO_URL=https://prod.trento.io \
  -v /host/config:/app/mcp-server-trento \
  mcp-server-trento

# Container with health checks enabled
docker run -p 5000:5000 -p 8080:8080 \
  -e TRENTO_MCP_PORT=5000 \
  -e TRENTO_MCP_ENABLE_HEALTH_CHECK=true \
  -e TRENTO_MCP_HEALTH_PORT=8080 \
  -e TRENTO_MCP_TRENTO_URL=https://prod.trento.io \
  -v /host/config:/app/mcp-server-trento \
  mcp-server-trento

Kubernetes Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server-trento
spec:
  template:
    spec:
      containers:
      - name: mcp-server-trento
        image: mcp-server-trento:latest
        env:
        - name: TRENTO_MCP_PORT
          value: "5000"
        - name: TRENTO_MCP_HEALTH_PORT
          value: "8080"
        - name: TRENTO_MCP_ENABLE_HEALTH_CHECK
          value: "true"
        - name: TRENTO_MCP_TRENTO_URL
          value: "https://prod.trento.io"
        - name: TRENTO_MCP_VERBOSITY
          value: "info"
        ports:
        - containerPort: 5000
          name: mcp
        - containerPort: 8080
          name: health

Help and Validation

You can see all available flags by running:

mcp-server-trento --help

The server will validate configuration on startup and log any issues with debug verbosity enabled.

Health Check Configuration

The mcp-server-trento includes built-in health check endpoints for monitoring and kubernetes integration.

Note: Health check functionality is disabled by default and must be explicitly enabled using the --enable-health-check flag or TRENTO_MCP_ENABLE_HEALTH_CHECK environment variable.

Health Check Endpoints

The health check server provides the following endpoints:

  • /livez - Liveness probe for kubernetes pod restart decisions

  • /readyz - Readiness probe for traffic routing decisions

The readiness endpoint performs comprehensive health checks including:

  • mcp-server - Validates MCP server connectivity using an MCP client

  • api-server - Verifies connectivity to the configured Trento API server

Enabling Health Checks

# Enable health checks with default port (8080)
mcp-server-trento --enable-health-check

# Enable with custom health port
mcp-server-trento --enable-health-check --health-port 9090

# Using environment variables
export TRENTO_MCP_ENABLE_HEALTH_CHECK=true
export TRENTO_MCP_HEALTH_PORT=8080
mcp-server-trento

Kubernetes Health Probes

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: mcp-server-trento
    image: mcp-server-trento:latest
    env:
    - name: TRENTO_MCP_ENABLE_HEALTH_CHECK
      value: "true"
    - name: TRENTO_MCP_HEALTH_PORT
      value: "8080"
    ports:
    - containerPort: 5000
      name: mcp
    - containerPort: 8080
      name: health
    livenessProbe:
      httpGet:
        path: /livez
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /readyz
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5

Testing Health Endpoints

# Test liveness endpoint
curl http://localhost:8080/livez

# Test readiness endpoint
curl http://localhost:8080/readyz

# Expected readiness response format:
# {"status":"up","checks":{"mcp-server":{"status":"up"},"api-server":{"status":"up"},"api-documentation":{"status":"up"}}}

# Expected liveness response format:
# {"status":"up"}