Skip to content

TLS

Where the proxy isWhat to do
On the same machine--http-addr=/run/gitlab-mcp/server.sock. No network hop to encrypt, no certificate to rotate
On another machine--tls-cert and --tls-key on the listener, with the proxy verifying it
Terminating for clientsThe proxy’s own certificate, plus one of the two rows above for the hop behind it

The unix socket removes the hop rather than encrypting it, and under Docker that hop is not “just loopback”: the path runs through docker-proxy and a bridge network. How the authentication budgets tell its callers apart is at the end of this page.

Terminal window
gitlab-mcp-server --http --http-addr=:8443 \
--gitlab-url=https://gitlab.example.com \
--tls-cert=/etc/ssl/mcp.crt --tls-key=/etc/ssl/mcp.key

Both flags or neither: a certificate without its key is a deployment that believes it is encrypting and is not, and startup refuses it. TLS 1.2 is the floor and no maximum is set, so a current client negotiates TLS 1.3 and 1.2 is reached only by a client that cannot go higher. Anything below 1.2 is refused. Both properties are pinned by tests that drive the real binary.

Write the new pair over the old paths. There is nothing else to do. The certificate is served through a callback that checks the two files on each handshake and re-reads them when either has changed, so the next handshake presents the new certificate. Connections already open keep the old one until they are replaced, which is correct and is how every rotation works.

Concretely, with certbot or any renewal tool that writes the same paths:

Terminal window
# The renewal hook needs no signal and no restart.
certbot renew --deploy-hook "true"

Three properties of that path, each covered by a test:

  • A half-written rotation keeps serving. Writing a certificate and its key is two writes, and between them the pair on disk does not match. The previously loaded certificate stays in service until the pair is whole again, and the failure is logged once rather than once per handshake.
  • Unreadable files keep serving. A renewal that unlinks before it writes, or a mount briefly absent, does not take the listener down.
  • Nothing is re-read while nothing changed. The staleness check is two stat calls; the parse happens only when the size or modification time moved.

There is no reload signal and none is needed. SIGHUP is not handled and, under its default disposition, terminates the process; do not send it.

The first load is still strict: at startup a path that does not exist or a key that does not match its certificate is a named startup error, because that is the one moment there is nothing to fall back to and an operator is watching.

The listener does not do mTLS. It requests no client certificate and verifies none; authentication on it is the bearer credential, in either supported mode. Mutual TLS at the edge is therefore a property of the proxy in front, which is where it belongs for a deployment with many clients anyway, since the proxy is what holds the client CA and the revocation list:

server {
listen 443 ssl;
server_name mcp.example.com;
ssl_client_certificate /etc/ssl/clients-ca.pem;
ssl_verify_client on;
ssl_verify_depth 2;
location / {
proxy_pass http://gitlab_mcp;
proxy_http_version 1.1;
proxy_set_header Connection "";
# Pass the verified identity on for logging, never for authorization:
# the server authorizes on the GitLab credential.
proxy_set_header X-Client-DN $ssl_client_s_dn;
}
}

For the proxy-to-server hop, proxy_ssl_verify on with proxy_ssl_trusted_certificate pointed at your private CA is the pairing for --tls-cert on the listener.

The unix socket and the authentication budgets

Section titled “The unix socket and the authentication budgets”

A unix socket has no peer address, so the authentication failure budgets, which are keyed on the caller’s address, have nothing to tell its callers apart by. Every connection to the socket is the one key unix.

Name the proxy on the socket as a trusted proxy and it tells the server who each caller is, exactly as a proxy on loopback TCP does:

Terminal window
gitlab-mcp-server --http --http-addr=/run/gitlab-mcp/server.sock \
--gitlab-url=https://gitlab.example.com \
--trusted-proxy-header=X-Real-IP --trusted-proxies=unix

unix trusts the peer of a connection on the socket and no address. The header is read by the same rule as from a TCP proxy (the first hop from the right that is not itself a listed proxy), so a chain of proxies lists the outer ones by address beside unix. Each caller then has budgets of its own, an IPv6 caller by the /64 it lies in (Authentication budgets).

Without the two flags every caller on the socket shares one budget: ten failed authentications a minute from anywhere behind the proxy spend it for everybody for a minute. A caller whose credential this deployment is already serving is still served while it is spent, so the damage is bounded to credentials the server does not currently hold: every one of them is answered 429 inside that window, a caller authenticating for the first time and one whose entry the pool has reclaimed alike (why the exemption is safe). That is fine where the caller population is small or entirely trusted.

Two pairings are refused at startup, because each trusts nobody while reading as if it trusted someone:

PairingWhy it is refused
A socket --http-addr whose --trusted-proxies lists addresses and no unixNo socket peer matches an address, so the header would never be believed and every caller would share one budget in silence
unix in --trusted-proxies on a TCP --http-addrNo connection to a TCP listener comes from a socket peer, so the entry would trust nobody

An earlier release started with the first pairing and ignored the header. If a deployment that worked before now refuses to start with --trusted-proxies does not name unix, add unix to the list.

Frequently asked questions

Can I rotate the TLS certificate without restarting?

Yes. Write the new pair over the same paths and the next handshake presents it; connections already open keep the old certificate until they are replaced. The certificate is served through a callback that stats both files on each handshake and re-reads them when either changed. A half-written pair, or files briefly unreadable, keeps the previous certificate in service and logs the reason once. No signal is needed, and SIGHUP is not a reload: it is unhandled and terminates the process.

Does the listener do mTLS?

No. It requests no client certificate and verifies none; authentication on it is the bearer credential, in either supported mode. Mutual TLS at the edge is a property of the proxy in front, which is where it belongs for a deployment with many clients anyway, since the proxy is what holds the client CA and the revocation list.

Is a unix socket the right choice for a same-machine proxy?

It removes the network hop rather than encrypting it, which is usually what you want. A unix socket has no peer address, so pass --trusted-proxy-header with --trusted-proxies=unix: the server then believes the address the proxy forwards from the socket, and each caller keeps an authentication failure budget of its own. Without them every caller on the socket shares one budget, and ten failed authentications a minute from anywhere spend it for everybody. A socket listener whose --trusted-proxies lists addresses but not unix refuses to start, since no socket peer matches an address.