Trento Docs :: Trento Documentation

Configuring Trento MCP Server

This section provides an overview of how to configure the Trento MCP Server depending on the deployment method.

Configuration in a Kubernetes deployment
Configuration in an systemd deployment

Configuration in a Kubernetes deployment

Configuration Sources

The Trento MCP Server supports multiple configuration sources with the following priority order (highest to lowest):

Environment variables - Used for containerized deployments.
Built-in defaults - Fallback values.

Configuration Overview

Environment Variable Default Value Description

Environment Variable	Default Value	Description
`TRENTO_MCP_AUTODISCOVERY_PATHS`	`/api/all/openapi,/wanda/api/all/openapi`	Custom paths for API autodiscovery.
`TRENTO_MCP_ENABLE_HEALTH_CHECK`	`false`	Enable the health check server.
`TRENTO_MCP_CONFIG`	(empty)	Configuration file path.
`TRENTO_MCP_HEADER_NAME`	`Authorization`	Header name used to pass the Trento API key to the Trento MCP Server.
`TRENTO_MCP_HEALTH_API_PATH`	`/api/healthz`	API path used for health checks on target servers.
`TRENTO_MCP_HEALTH_PORT`	`8080`	Port where the health check server runs.
`TRENTO_MCP_INSECURE_SKIP_TLS_VERIFY`	`false`	Skip TLS certificate verification when fetching OAS specs from HTTPS.
`TRENTO_MCP_OAS_PATH`	`[]`	Path(s) to OpenAPI specification file(s). Can be set multiple times.
`TRENTO_MCP_PORT`	`5000`	Port where the Trento MCP Server runs.
`TRENTO_MCP_TAG_FILTER`	`["MCP"]`	Only include operations that contain one of these tags.
`TRENTO_MCP_TRANSPORT`	`streamable`	Protocol to use: `streamable` or `sse`.
`TRENTO_MCP_TRENTO_URL`	(empty)	Target Trento server URL. Required for autodiscovery if OAS path is not set.
`TRENTO_MCP_VERBOSITY`	`info`	Log level: `debug`, `info`, `warning`, or `error`.

TRENTO_MCP_AUTODISCOVERY_PATHS

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

Custom paths for API autodiscovery.

TRENTO_MCP_ENABLE_HEALTH_CHECK

false

Enable the health check server.

TRENTO_MCP_CONFIG

(empty)

Configuration file path.

TRENTO_MCP_HEADER_NAME

Authorization

Header name used to pass the Trento API key to the Trento MCP Server.

TRENTO_MCP_HEALTH_API_PATH

/api/healthz

API path used for health checks on target servers.

TRENTO_MCP_HEALTH_PORT

8080

Port where the health check server runs.

TRENTO_MCP_INSECURE_SKIP_TLS_VERIFY

false

Skip TLS certificate verification when fetching OAS specs from HTTPS.

TRENTO_MCP_OAS_PATH

[]

Path(s) to OpenAPI specification file(s). Can be set multiple times.

TRENTO_MCP_PORT

5000

Port where the Trento MCP Server runs.

TRENTO_MCP_TAG_FILTER

["MCP"]

Only include operations that contain one of these tags.

TRENTO_MCP_TRANSPORT

streamable

Protocol to use: streamable or sse.

TRENTO_MCP_TRENTO_URL

(empty)

Target Trento server URL. Required for autodiscovery if OAS path is not set.

TRENTO_MCP_VERBOSITY

info

Log level: debug, info, warning, or error.

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://trento.example.com"
        - name: TRENTO_MCP_VERBOSITY
          value: "info"
        ports:
        - containerPort: 5000
          name: mcp
        - containerPort: 8080
          name: health

Configuration in an systemd deployment

Configuration Sources

The Trento MCP Server supports multiple configuration sources with the following priority order (highest to lowest):

Command-line flags - Override config for the current process.
Configuration file - Persistent settings configuration.

Configuration Overview

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, configuration variables, and default values.

Flag Config Variable Default Value Description

Flag	Config Variable	Default Value	Description
`--autodiscovery-paths, -A`	`AUTODISCOVERY_PATHS`	`/api/all/openapi,/wanda/api/all/openapi`	Custom paths for API autodiscovery.
`--config, -c`	(empty)	(empty)	Configuration file path.
`--enable-health-check, -d`	`ENABLE_HEALTH_CHECK`	`false`	Enable the health check server.
`--header-name, -H`	`HEADER_NAME`	`Authorization`	Header name used to pass the Trento API key to the Trento MCP Server.
`--health-api-path, -a`	`HEALTH_API_PATH`	`/api/healthz`	API path used for health checks on target servers.
`--health-port, -z`	`HEALTH_PORT`	`8080`	Port where the health check server runs.
`--insecure-skip-tls-verify, -i`	`INSECURE_SKIP_TLS_VERIFY`	`false`	Skip TLS certificate verification when fetching OAS specs from HTTPS.
`--oas-path, -P`	`OAS_PATH`	`[]`	Path(s) to OpenAPI specification file(s). Can be set multiple times.
`--port, -p`	`PORT`	`5000`	Port where the Trento MCP Server runs.
`--tag-filter, -f`	`TAG_FILTER`	`["MCP"]`	Only include operations that contain one of these tags.
`--transport, -t`	`TRANSPORT`	`streamable`	Protocol to use: `streamable` or `sse`.
`--trento-url, -u`	`TRENTO_URL`	(empty)	Target Trento server URL. Required for autodiscovery if OAS path is not set.
`--verbosity, -v`	`VERBOSITY`	`info`	Log level: `debug`, `info`, `warning`, or `error`.

--autodiscovery-paths, -A

AUTODISCOVERY_PATHS

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

Custom paths for API autodiscovery.

--config, -c

(empty)

Configuration file path.

--enable-health-check, -d

ENABLE_HEALTH_CHECK

false

Enable the health check server.

--header-name, -H

HEADER_NAME

Authorization

Header name used to pass the Trento API key to the Trento MCP Server.

--health-api-path, -a

HEALTH_API_PATH

/api/healthz

API path used for health checks on target servers.

--health-port, -z

HEALTH_PORT

8080

Port where the health check server runs.

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

INSECURE_SKIP_TLS_VERIFY

false

Skip TLS certificate verification when fetching OAS specs from HTTPS.

--oas-path, -P

OAS_PATH

[]

Path(s) to OpenAPI specification file(s). Can be set multiple times.

--port, -p

PORT

5000

Port where the Trento MCP Server runs.

--tag-filter, -f

TAG_FILTER

["MCP"]

Only include operations that contain one of these tags.

--transport, -t

TRANSPORT

streamable

Protocol to use: streamable or sse.

--trento-url, -u

TRENTO_URL

(empty)

Target Trento server URL. Required for autodiscovery if OAS path is not set.

--verbosity, -v

VERBOSITY

info

Log level: debug, info, warning, or error.

Configure Trento MCP Server with Command-Line Flags

Trento MCP Server allows you to override configuration settings using command-line flags for temporary changes. These overrides are not persistent and are lost when the process stops or the system is rebooted. To make configuration changes permanent for the systemd service, update /etc/trento/mcp-server-trento and restart the service.

Basic usage with custom port, verbosity, and target URL:

mcp-server-trento --port 9000 --verbosity debug --trento-url https://trento.example.com

Using multiple OpenAPI specifications:

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

Autodiscovery with custom paths:

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

Enable health checks on a custom port:

mcp-server-trento --enable-health-check --health-port 8080 --port 5000

Help and Validation

You can see all available flags by running:

mcp-server-trento --help

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

Health Check Configuration

The Trento MCP Server includes built-in health check endpoints for systemd and Kubernetes integration.

Health check functionality is disabled by default and must be explicitly enabled using the --enable-health-check flag or the 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 Trento MCP Server connectivity using an MCP client.
api-server - Verifies connectivity to the configured Trento API server.

Enable Health Checks with Helm on a Kubernetes deployment

Enable health checks when deploying on Kubernetes with Helm:

helm upgrade \
  --install trento-server oci://registry.suse.com/trento/trento-server \
  --set global.trentoWeb.origin=TRENTO_SERVER_HOSTNAME \
  --set trento-web.adminUser.password=ADMIN_PASSWORD \
  --set trento-mcp-server.enabled=true \
  --set TRENTO_MCP_ENABLE_HEALTH_CHECK=true \
  --set TRENTO_MCP_HEALTH_PORT=8080

The health port is internal to the Kubernetes cluster. To reach it from the host running Kubernetes, forward the Pod port. Replace NAMESPACE with your target namespace (Helm defaults to default).

kubectl port-forward --namespace NAMESPACE \
  $(kubectl get pods --namespace NAMESPACE -l app.kubernetes.io/name=mcp-server -o jsonpath="{.items[0].metadata.name}") \
  8080:8080 &

With the port forward active, test the endpoints in Testing Health Endpoints.

Enable Health Checks with the command-line for systemd deployment

mcp-server-trento --enable-health-check

mcp-server-trento --enable-health-check --health-port 8080

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"}

Troubleshooting

This section provides solutions for common issues when deploying and using the Trento MCP Server.

Connection Issues

Trento MCP Server cannot connect to Trento API
- Verify the TRENTO_URL or OAS_PATH configuration points to accessible endpoints
- Check network connectivity between the Trento MCP Server and Trento components
- Ensure API authentication is properly configured with valid tokens
MCP clients cannot connect to Trento MCP Server
- Verify the Trento MCP Server is running and listening on the correct port (default: 5000)
- Check firewall rules allow access to the Trento MCP Server port
- Ensure the Trento MCP Server endpoint URL is correctly configured in client applications

Authentication Issues

API token authentication fails
- Verify the Personal Access Token is valid and not expired
- Ensure the token has the necessary permissions in Trento
- Check that the HEADER_NAME configuration matches between server and client
Token not accepted
- Confirm the token was generated from the correct Trento instance
- Verify the token format and ensure it includes the "Bearer " prefix if required

Configuration Issues

OpenAPI specification not found
- Check that TRENTO_URL or OAS_PATH point to valid Trento API endpoints
- Verify the Trento Web and Trento Wanda services are running and accessible
- Ensure autodiscovery paths are correct if using TRENTO_URL
Tools not appearing in MCP clients
- Check the TAG_FILTER configuration - only operations with matching tags are exposed
- Verify the OpenAPI specifications are accessible and valid
- Ensure the Trento MCP Server can parse the API documentation

Performance Issues

Slow response times
- Check network latency between Trento MCP Server and Trento components
- Review Trento API performance and database query times
- Consider enabling debug logging to identify bottlenecks
High resource usage
- Monitor Trento MCP Server memory and CPU usage
- Check for memory leaks in long-running processes
- Consider adjusting logging verbosity to reduce I/O overhead

Health Check Issues

Health checks failing
- Verify health check endpoints are accessible
- Check that all required services (Trento API, Trento MCP Server) are responding
- Review health check configuration and timeouts

Logging and Debugging

Enable debug logging
- Set VERBOSITY=debug to get detailed logs
- Check Trento MCP Server logs for error messages and connection attempts
- Review Trento component logs for API-related issues
Common log messages
- "Failed to fetch OpenAPI specification" - Check API endpoint accessibility
- "Authentication failed" - Verify API token configuration
- "No tools available" - Check tag filtering and API documentation

Getting Help

If you continue to experience issues:

Check the Trento MCP Server logs for detailed error messages
Verify configuration values:
1. For systemd deployments, use mcp-server-trento --help
2. For Kubernetes deployments, run Helm with --render-subchart-notes to view the rendered Trento MCP Server settings
Test API connectivity directly using curl or similar tools
Check the Trento server logs for API authentication and access issues