Skip to content
Nov 3, 2026 - Version 2026.10 has been released
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Throughout this page, replace datasentinel.example.com with the fully-qualified public hostname of your own Datasentinel API: the name your TLS certificate was issued for.

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 -f returns the short name rather than an FQDN;

  • getent hosts $(hostname) shows only a link-local (fe80::…) or loopback (127.x) address;

  • getfqdn() returns localhost.localdomain or the short name;

  • DS_MCP_PUBLIC_URL is absent from the service's environment, or empty (DS_MCP_PUBLIC_URL=).

The fix

1

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_mcp service, on the machine where that service runs. Setting it in your MCP client's config does nothing: if the client uses mcp-remote, that config's env block 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.

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.

2

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.

What does not work: adding search example.com to /etc/resolv.conf. The search suffix is applied only to forward lookups of short names, and getfqdn() reads the reverse direction. An A record alone is insufficient for the same reason.

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.

3

Remove any TLS-verification bypass

If your client config contains something like:

remove it once the real fix is in place. It disables certificate validation for every TLS connection that Node process makes, and it does not help with this error anyway: the failing handshake is in Python, not Node.

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