The OpenEdge MCP Server supports flexible certificate configuration for both server-side TLS and mTLS authentication. The following table lists the supported file formats and their purpose. This topic explains how to configure TLS and mutual TLS (mTLS) certificates for the OpenEdge MCP Server.

Certificate file requirements

The OpenEdge MCP Server supports flexible certificate configuration for both server-side TLS and mTLS authentication. The following table lists the supported file formats and their purpose:
Format Purpose
.pem Preferred format for certificates
.crt Alternative format for certificates
.key Used for private keys
TLS requires specific files to enable secure communication. The following table lists these required files for TLS:
File Purpose
certfile Server certificate containing public key and certificate chain
keyfile Server private key
mTLS adds the following additional files for client certificate validation:
File Purpose
client_cafile Client Certificate Authority bundle for validating client certificates (mTLS only)
require_client_cert Must be set to true to enforce client certificate validation

File naming conventions

You can use any filenames for certificates because the server reads certificate paths from configuration. The following table shows default names generated when using mcpgen or development certificate generation:
Certificate type File name
Server certificate localhost.pem
Server private key localhost-key.pem
Alternative server cert localhost.crt
Client CA bundle client-ca.pem
Client certificate client.pem
Client private key client.key
Combined client cert and key client-combined.pem
Alternative client certificate client.crt

Configuration examples

The following examples demonstrate how to configure TLS and mTLS in the runtime configuration.
  • This example shows the basic TLS configuration (server-only):
    {
  "runtime": {
    "server": {
      "transport": {
        "tls": {
          "certfile": "./certs/my-server.pem",
          "keyfile": "./certs/my-server-key.pem"
        }
      }
    }
  }
}
  • This example shows the mTLS configuration:
    {
  "runtime": {
    "server": {
      "transport": {
        "tls": {
          "certfile": "./certs/server.crt",
          "keyfile": "./certs/server.key",
          "client_cafile": "./certs/trusted-clients-ca.pem",
          "require_client_cert": true
        }
      }
    }
  }
}
  • This example showshow to use custom certificate names:
    {
  "runtime": {
    "server": {
      "transport": {
        "tls": {
          "certfile": "./ssl/company-api-server.crt",
          "keyfile": "./ssl/company-api-private.key",
          "keyfile_password": "optional-password-for-encrypted-key"
        }
      }
    }
  }
}

Override configuration with environment variables

You can override TLS configuration using environment variables. The following table lists the supported variables:
Environment variable Configuration path Purpose
SSL_CERTFILE runtime.server.transport.tls.certfile Server certificate file path
SSL_KEYFILE runtime.server.transport.tls.keyfile Server private key file path
SSL_CLIENT_CAFILE runtime.server.transport.tls.client_cafile Client CA certificate for mTLS
SSL_REQUIRE_CLIENT_CERT runtime.server.transport.tls.require_client_cert Set to 1 to require client certificates
SSL_KEYFILE_PASSWORD runtime.server.transport.tls.keyfile_password Password for encrypted private keys

Behavioral considerations for TLS and mTLS

The following behaviors apply when configuring TLS and mTLS:
  • File existence validation— TLS activation depends on the presence of required certificate files. The following points summarize this behavior:
    • TLS is enabled only when both certfile and keyfile exist on disk.
    • If any certificate file is missing, the server falls back to HTTP without TLS.
    • This fallback prevents misleading logs that might indicate TLS is enabled when certificates are not properly mounted.
  • Path resolution—The server resolves certificate file paths based on the following rules:
    • Relative paths are resolved from the working directory where the server starts.
    • Absolute paths are used as provided in the configuration.
    • Ensure that all certificate files have proper file permissions so they are readable by the server process.
  • Certificate validation logic—The server performs validation checks during startup to ensure certificate integrity:
    • The server verifies that both certificate and key files are accessible.
    • TLS activation fails if the certificate and private key do not match or are invalid.
    • For mTLS, a valid client_cafile is required when require_client_cert is set to true.

Security best practices

Follow these best practices to maintain security:
  • File Permissions—Set certificate files to be readable only by the server process, for example chmod 600.
  • Key Protection—Never commit private keys to version control.
  • Certificate Rotation—Implement regular certificate rotation. For more information, see Upgrade process and key or certificate rotation.
  • Hostname Validation—Ensure certificates include appropriate Subject Alternative Names (SANs).
  • Strong Ciphers—Use modern TLS versions and strong cipher suites in production.

Generate certificates for development

Use the following commands to generate development certificates:
# Generate development certificates with custom hostnames
./mcpgen up --tls --extra-hostnames "api.example.com,staging.example.com"

# Generate mTLS certificates (includes client certificates)
./mcpgen up --mtls --extra-hostnames "api.example.com,staging.example.com"

For production certificate management and rotation procedures, see Upgrade process and key or certificate rotation.

Troubleshoot common issues

The following table lists common issues and their resolutions:
Issue Resolution
"TLS disabled, falling back to HTTP" Verify that both certfile and keyfile paths exist and are readable
Certificate validation errors Check that the certificate and private key match using OpenSSL tools
mTLS handshake failures Ensure the client CA bundle includes the signing CA for client certificates
Hostname mismatches Add required hostnames to certificate SANs or use wildcard certificates