TLS hostname mismatch on API calls
Every MCP tool call fails with "Hostname mismatch" during the TLS handshake. Set DS_MCP_PUBLIC_URL on the datasentinel_mcp service to fix it.
Applies to: a self-hosted Datasentinel MCP server (the datasentinel_mcp service) whose tool calls fail during the TLS handshake with the API.
Symptom
Every Datasentinel MCP tool call fails immediately, before returning any data:
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
Hostname mismatch, certificate is not valid for '<short-hostname>'. (_ssl.c:1000)The name in the error is the short hostname of the machine running the MCP server, the bare label with no domain attached. The failure is total: no instance list, no analysis, no platform status.
Reading the error
Two details identify the failure precisely.
The name is short, not fully-qualified. A public certificate can never cover a bare label: Let's Encrypt and other public CAs will not issue for a name that isn't publicly resolvable. So whatever built the URL used the machine's short hostname rather than the API's public name.
_ssl.c:1000 means the failure is in Python. That is CPython's SSL module. If your MCP client uses mcp-remote (Node), a client-side TLS failure would surface as ERR_TLS_CERT_ALTNAME_INVALID or UNABLE_TO_VERIFY_LEAF_SIGNATURE, never a _ssl.c line number. The failing handshake is therefore inside the Python MCP server process, on its onward call to the Datasentinel API.
There are two legs, and only the second one is broken:
The first leg succeeds. The second one fails the certificate check.
This matters because it tells you where not to look. Check these off and move on:
The certificate is usually fine. Confirm it is current and issued for your public FQDN:
If it is, it is not the cause.
The client config is usually fine. If your
.mcp.json(or equivalent) already points at the fully-qualified URL, the client leg is correct. The problem is downstream of it.
Root cause
The MCP server has one deployment setting, its public URL: the HTTPS origin nginx serves, for example https://datasentinel.example.com. It drives everything that names the server, the OAuth discovery documents and login page, and also the server's own onward hop to the Datasentinel API, <public URL>/ds-api, which goes through the same nginx.
When the environment variable DS_MCP_PUBLIC_URL is not set, the server derives that URL from the machine's own identity: https:// followed by the name socket.getfqdn() returns, with fallbacks when that name resolves to localhost. On a host whose fully-qualified name cannot be determined, that fallback chain yields the short hostname, which no public certificate matches.
The reason the fallback fails is specific and worth understanding, because it is not obvious:
On a machine with no /etc/hosts entry and no PTR record, systemd's nss-myhostname module answers the lookup with a synthesised link-local or loopback address, whose reverse lookup resolves to localhost.localdomain or to nothing dotted at all. The fallback then degrades further and ends up at the short static hostname.
Confirming the diagnosis
Run these on the machine running the datasentinel_mcp service:
You have confirmed this issue if:
hostname -freturns the short name rather than an FQDN;getent hosts $(hostname)shows only a link-local (fe80::…) or loopback (127.x) address;getfqdn()returnslocalhost.localdomainor the short name;DS_MCP_PUBLIC_URLis absent from the service's environment, or empty (DS_MCP_PUBLIC_URL=).
The fix
Set DS_MCP_PUBLIC_URL (this is the one that fixes it)
DS_MCP_PUBLIC_URL is the environment variable the Datasentinel MCP server reads for its public URL. It builds the API base URL from it, as $DS_MCP_PUBLIC_URL/ds-api, and the OAuth issuer and login URLs as well. Setting it bypasses the hostname-detection fallback entirely.
Its value is the public HTTPS origin of your Datasentinel platform, with the exact name on the TLS certificate. Scheme and hostname, nothing else: no path, and no port unless clients connect on one.
Because the same value is advertised to assistants as the OAuth issuer, it must be the name they connect to. A different name here would make the sign-in fail after the certificate error is gone.
Two things to get right:
It must be set in the environment of the
datasentinel_mcpservice, on the machine where that service runs. Setting it in your MCP client's config does nothing: if the client usesmcp-remote, that config'senvblock reaches only the local Node process, never the remote Python one.It must match the certificate. If the certificate carries several names (SANs), use the one clients actually connect to. A mismatch here produces the same error you started with.
The cleanest method. It survives package upgrades and reinstallations, since it doesn't touch the shipped unit file:
In the editor that opens, add:
Save and exit, then reload and restart:
Verify it took effect, including on the OAuth side, whose discovery document must now advertise the public origin as issuer:
If you prefer to keep configuration outside systemd units, or already have a settings file for this service:
Then reference it from a drop-in (sudo systemctl edit datasentinel_mcp):
Followed by the same daemon-reload and restart. Note that EnvironmentFile lines are plain KEY=value, with no export and no shell quoting.
Fix the host's FQDN (worth doing anyway)
Even with DS_MCP_PUBLIC_URL set, a machine that cannot state its own fully-qualified name will cause confusion elsewhere: in logs, in certificates issued by ACME clients, in anything else calling getfqdn().
Find the machine's real address, set the static hostname to the FQDN, and register it in /etc/hosts:
The FQDN must come first on the /etc/hosts line. getfqdn() takes the canonical name, which is the first field after the address, so putting the short name first defeats the fix.
Verify:
A PTR record for the host's address pointing at the FQDN achieves the same thing (dig -x <address> +short to verify), and is the better answer where you control reverse DNS. On a cloud VM behind NAT you often don't, because the address is private and any reverse record is assigned by the provider, so the /etc/hosts entry is the pragmatic route. files is consulted before dns in /etc/nsswitch.conf, so it wins either way.
If NetworkManager manages the hostname, a DHCP lease renewal may revert it. Use hostnamectl set-hostname --static and consider dns=none or an explicit hostname-mode setting in the NetworkManager configuration.
Verifying the fix
Restart the service and call the platform status tool from your MCP client:
A healthy response reports "status": "OK" with the backend version and every service (nginx, Grafana, PostgreSQL, backend, dispatcher, InfluxDB) running.
If the SSL error persists, re-check that the name in the error is now the FQDN. If it is, the mismatch is genuinely between your certificate and that name, which is a different problem from this one.
Checklist
Why this happens at all
The underlying design issue is that deriving a public API endpoint from the machine's own identity only works when the two happen to coincide, on a single-homed bare-metal host with correct reverse DNS. It breaks behind a load balancer, in a container, on a replica, and on any cloud VM whose internal name differs from its public one.
DS_MCP_PUBLIC_URL exists precisely so you don't depend on that coincidence. Set it explicitly on every deployment, including ones where the fallback currently happens to work. It costs one line and removes an entire class of failure that surfaces as an opaque TLS error rather than a configuration one.
Last updated