TLS Configuration

Configure TLS (Transport Layer Security) for secure connections to MCP servers, including certificate verification and mutual TLS authentication.

Basic TLS Configuration

[mcp.servers.secure]
url = "https://api.secure.com/mcp"

[mcp.servers.secure.tls]
verify_certs = true                           # Verify server certificates
accept_invalid_hostnames = false              # Reject hostname mismatches
root_ca_cert_path = "/etc/ssl/certs/ca.pem"   # Custom CA certificate

# Client certificates for mutual TLS
client_cert_path = "/etc/ssl/certs/client.pem"
client_key_path = "/etc/ssl/private/client.key"

Configuration Options

  • verify_certs: Whether to verify server certificates (default: true)
  • accept_invalid_hostnames: Accept certificates with hostname mismatches (default: false)
  • root_ca_cert_path: Path to custom root CA certificate (optional, default: system CA)
  • client_cert_path: Path to client certificate for mTLS (optional)
  • client_key_path: Path to client private key for mTLS (optional)

Certificate Verification

Standard Verification

Default configuration with system CA certificates:

[mcp.servers.api]
url = "https://api.example.com/mcp"

[mcp.servers.api.tls]
verify_certs = true  # Default - verifies against system CAs

Custom CA Certificate

For self-signed or internal CA certificates:

[mcp.servers.internal]
url = "https://internal.company.com/mcp"

[mcp.servers.internal.tls]
verify_certs = true
root_ca_cert_path = "/etc/nexus/certs/company-ca.pem"

Skip Verification (Development Only)

Warning: Only use in development environments:

[mcp.servers.dev]
url = "https://dev.localhost:8443/mcp"

[mcp.servers.dev.tls]
verify_certs = false  # Dangerous - development only!

Mutual TLS (mTLS)

Configuration

For services requiring client certificates:

[mcp.servers.high_security]
url = "https://secure.example.com/mcp"

[mcp.servers.high_security.tls]
verify_certs = true
client_cert_path = "/etc/nexus/certs/client.pem"
client_key_path = "/etc/nexus/certs/client-key.pem"

With Custom CA and mTLS

Complete configuration for maximum security:

[mcp.servers.enterprise]
url = "https://api.enterprise.com/mcp"

[mcp.servers.enterprise.auth]
token = "{{ env.ENTERPRISE_TOKEN }}"

[mcp.servers.enterprise.tls]
verify_certs = true
accept_invalid_hostnames = false
root_ca_cert_path = "/etc/nexus/certs/enterprise-ca.pem"
client_cert_path = "/etc/nexus/certs/nexus-client.pem"
client_key_path = "/etc/nexus/certs/nexus-client-key.pem"

Certificate Management

Certificate Formats

All certificates must be in PEM format:

# View certificate details
openssl x509 -in certificate.pem -text -noout

# Convert DER to PEM
openssl x509 -inform DER -in certificate.der -out certificate.pem

# Convert PKCS12 to PEM
openssl pkcs12 -in certificate.p12 -out certificate.pem -nodes

File Permissions

Secure certificate files properly:

# CA certificate (readable)
chmod 644 /etc/nexus/certs/ca.pem

# Client certificate (readable)
chmod 644 /etc/nexus/certs/client.pem

# Private key (restricted)
chmod 600 /etc/nexus/certs/client-key.pem
chown nexus:nexus /etc/nexus/certs/client-key.pem

Certificate Rotation

Best practices for certificate management:

  1. Monitor Expiration:

    # Check certificate expiration
openssl x509 -in cert.pem -noout -enddate

  2. Automate Renewal:

    • Use cert-manager for Kubernetes
    • Use Let's Encrypt with automatic renewal
    • Set up monitoring alerts 30 days before expiration

  3. Graceful Rotation:

    • Update certificates during maintenance windows
    • Test new certificates in staging first
    • Keep old certificates briefly for rollback

Common Configurations

Internal Services

For internal corporate services:

[mcp.servers.corp_api]
url = "https://api.internal.corp/mcp"

[mcp.servers.corp_api.tls]
verify_certs = true
root_ca_cert_path = "/etc/nexus/certs/corp-ca-chain.pem"

Cloud Services

For cloud provider endpoints:

[mcp.servers.aws_service]
url = "https://service.amazonaws.com/mcp"

[mcp.servers.aws_service.tls]
verify_certs = true  # Uses system CA bundle

Development with Self-Signed

For local development:

[mcp.servers.local_dev]
url = "https://localhost:8443/mcp"

[mcp.servers.local_dev.tls]
verify_certs = true
accept_invalid_hostnames = true  # Allow localhost mismatch
root_ca_cert_path = "/home/dev/certs/dev-ca.pem"

High-Security Environment

For maximum security:

[mcp.servers.banking]
url = "https://api.bank.com/mcp"

[mcp.servers.banking.auth]
type = "forward"  # OAuth2 token forwarding

[mcp.servers.banking.tls]
verify_certs = true
accept_invalid_hostnames = false
root_ca_cert_path = "/etc/nexus/certs/banking-ca.pem"
client_cert_path = "/etc/nexus/certs/banking-client.pem"
client_key_path = "/etc/nexus/certs/banking-client-key.pem"

Troubleshooting

Certificate Verification Errors

"certificate verify failed":

  • Check certificate is not expired
  • Verify CA certificate is correct
  • Ensure certificate chain is complete
  • Check system time is correct

"hostname mismatch":

  • Certificate CN/SAN doesn't match hostname
  • Consider using accept_invalid_hostnames for development
  • Request new certificate with correct hostname

Connection Issues

"unable to get local issuer certificate":

# Solution: Provide CA certificate
[mcp.servers.api.tls]
root_ca_cert_path = "/path/to/ca-certificate.pem"

"sslv3 alert bad certificate":

# Solution: Provide client certificate for mTLS
[mcp.servers.api.tls]
client_cert_path = "/path/to/client-cert.pem"
client_key_path = "/path/to/client-key.pem"

Testing TLS Configuration

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

# Test with custom CA
openssl s_client -connect api.example.com:443 \
  -CAfile /etc/nexus/certs/ca.pem

# Test mutual TLS
openssl s_client -connect api.example.com:443 \
  -cert client.pem -key client-key.pem

# Test with curl
curl --cacert ca.pem --cert client.pem --key client-key.pem \
  https://api.example.com/mcp

Security Best Practices

  1. Always Verify Certificates in Production:

    [mcp.servers.production.tls]
verify_certs = true  # Never set to false in production

  2. Use Strong Cipher Suites:

    • Prefer TLS 1.2 or higher
    • Disable weak ciphers at server level

  3. Protect Private Keys:

    • Store with restricted permissions (600)
    • Use hardware security modules (HSM) for high-value keys
    • Never commit keys to version control

  4. Certificate Pinning:

    • Pin CA certificates for critical services
    • Document pinned certificates
    • Plan for certificate rotation

  5. Monitor Certificate Health:

    • Set up expiration alerts
    • Monitor for revoked certificates
    • Log TLS handshake failures

Integration with Other Features

With Authentication

Combine TLS with authentication:

[mcp.servers.secure_api]
url = "https://api.secure.com/mcp"

[mcp.servers.secure_api.auth]
token = "{{ env.API_TOKEN }}"

[mcp.servers.secure_api.tls]
verify_certs = true
client_cert_path = "/etc/nexus/certs/client.pem"
client_key_path = "/etc/nexus/certs/client-key.pem"

With Rate Limiting

Secure high-value endpoints:

[mcp.servers.premium_api]
url = "https://premium.example.com/mcp"

[mcp.servers.premium_api.tls]
verify_certs = true
client_cert_path = "/etc/nexus/certs/premium-client.pem"
client_key_path = "/etc/nexus/certs/premium-client-key.pem"

[mcp.servers.premium_api.rate_limits]
limit = 100
interval = "3600s"

Next Steps

© Grafbase, Inc.