Version:

This project is part of pgEdge Labs and is under active development. APIs and features may change without notice.

TLS Configuration

This guide covers configuring TLS (Transport Layer Security) for secure HTTPS connections in the MCP Bridge.

Overview

TLS provides:

Encryption: Protects data in transit from eavesdropping
Authentication: Verifies server identity (and optionally client identity with mTLS)
Integrity: Ensures data hasn't been tampered with

Server Mode TLS

Basic HTTPS Setup

Enable HTTPS with a certificate and private key:

mode: server

server:
  listen: ":8443"

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"

TLS Version Configuration

Configure minimum and maximum TLS versions:

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  min_version: "1.2"  # Minimum TLS 1.2 (recommended)
  max_version: "1.3"  # Maximum TLS 1.3

Supported versions: "1.0", "1.1", "1.2", "1.3"

Warning

TLS 1.0 and 1.1 are deprecated. Always use TLS 1.2 or higher in production.

Cipher Suite Configuration

Configure allowed cipher suites for TLS 1.2:

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  min_version: "1.2"
  cipher_suites:
    - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
    - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
    - "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
    - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
    - "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256"
    - "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"

Note

TLS 1.3 uses a fixed set of cipher suites and ignores this configuration.

Curve Preferences

Configure elliptic curve preferences for key exchange:

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  curve_preferences:
    - "X25519"   # Recommended
    - "P-256"
    - "P-384"

Mutual TLS (mTLS)

Mutual TLS requires clients to present certificates, providing two-way authentication.

Server Configuration for mTLS

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  client_ca_file: "/etc/mcp-bridge/tls/client-ca.crt"
  client_auth: "verify"

Client Authentication Modes

Mode	Description
`none`	No client certificate required
`request`	Request client certificate but don't require it
`require`	Require client certificate but don't verify
`verify`	Require and verify client certificate (full mTLS)

mTLS Example

mode: server

server:
  listen: ":8443"

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  client_ca_file: "/etc/mcp-bridge/tls/client-ca.crt"
  client_auth: "verify"
  min_version: "1.2"

Client Mode TLS

Custom CA Certificate

Use a custom CA to verify the server certificate:

mode: client

client:
  url: "https://mcp.example.com/mcp"

tls:
  ca_cert: "/etc/ssl/certs/custom-ca.crt"

Client Certificates for mTLS

Provide client certificates when the server requires mTLS:

mode: client

client:
  url: "https://mcp.example.com/mcp"

tls:
  ca_cert: "/etc/ssl/certs/server-ca.crt"
  cert_file: "/etc/mcp-bridge/tls/client.crt"
  key_file: "/etc/mcp-bridge/tls/client.key"

Server Name Indication (SNI)

Override the server name for certificate verification:

tls:
  ca_cert: "/etc/ssl/certs/ca.crt"
  server_name: "mcp.example.com"

Skip Certificate Verification

For development environments only:

tls:
  insecure_skip_verify: true

Danger

Never use insecure_skip_verify: true in production. It disables all certificate verification, making connections vulnerable to man-in-the-middle attacks.

Generating Certificates

Self-Signed CA and Server Certificate

# Generate CA private key
openssl genrsa -out ca.key 4096

# Generate CA certificate
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/CN=MCP Bridge CA"

# Generate server private key
openssl genrsa -out server.key 2048

# Generate server certificate signing request
openssl req -new -key server.key -out server.csr \
  -subj "/CN=mcp.example.com"

# Sign server certificate with CA
openssl x509 -req -days 365 -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt \
  -extfile <(printf "subjectAltName=DNS:mcp.example.com,DNS:localhost,IP:127.0.0.1")

Client Certificate for mTLS

# Generate client private key
openssl genrsa -out client.key 2048

# Generate client certificate signing request
openssl req -new -key client.key -out client.csr \
  -subj "/CN=mcp-client"

# Sign client certificate with CA
openssl x509 -req -days 365 -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt

Using Let's Encrypt

For production, use certificates from a trusted CA like Let's Encrypt:

# Using certbot
certbot certonly --standalone -d mcp.example.com

# Certificates will be in /etc/letsencrypt/live/mcp.example.com/

tls:
  enabled: true
  cert_file: "/etc/letsencrypt/live/mcp.example.com/fullchain.pem"
  key_file: "/etc/letsencrypt/live/mcp.example.com/privkey.pem"

Complete TLS Examples

Production Server with TLS

mode: server

server:
  listen: ":443"

tls:
  enabled: true
  cert_file: "/etc/letsencrypt/live/mcp.example.com/fullchain.pem"
  key_file: "/etc/letsencrypt/live/mcp.example.com/privkey.pem"
  min_version: "1.2"

auth:
  type: bearer
  bearer:
    tokens:
      - "${MCP_AUTH_TOKEN}"

mcp:
  command: "/usr/local/bin/mcp-server"

mTLS Server

mode: server

server:
  listen: ":8443"

tls:
  enabled: true
  cert_file: "/etc/mcp-bridge/tls/server.crt"
  key_file: "/etc/mcp-bridge/tls/server.key"
  client_ca_file: "/etc/mcp-bridge/tls/client-ca.crt"
  client_auth: "verify"
  min_version: "1.2"
  cipher_suites:
    - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
    - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
  curve_preferences:
    - "X25519"
    - "P-256"

mcp:
  command: "/usr/local/bin/mcp-server"

mTLS Client

mode: client

client:
  url: "https://mcp.example.com:8443/mcp"

tls:
  ca_cert: "/etc/mcp-bridge/tls/server-ca.crt"
  cert_file: "/etc/mcp-bridge/tls/client.crt"
  key_file: "/etc/mcp-bridge/tls/client.key"

Troubleshooting

Certificate Errors

"x509: certificate signed by unknown authority"

Add the CA certificate to ca_cert or system trust store
Verify the certificate chain is complete

"x509: certificate is not valid for"

Check that the server name matches the certificate's CN or SAN
Use server_name to specify the expected name

"tls: bad certificate"

Client certificate is missing or invalid
Verify the client certificate is signed by the expected CA

Debugging TLS

Enable debug logging:

logging:
  level: debug

Test with OpenSSL:

# Test server certificate
openssl s_client -connect mcp.example.com:443 -servername mcp.example.com

# Test with client certificate
openssl s_client -connect mcp.example.com:8443 \
  -cert client.crt -key client.key -CAfile ca.crt

Next Steps

Authentication - Configure authentication
Configuration Reference - Full configuration options