> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/ai-connector/troubleshooting/ssl-certificates.md).

# Self-signed and untrusted TLS certificates

Your assistant rejects the connection because the platform serves a self-signed or internal-CA TLS certificate. Fix it per assistant, without turning verification off.

**Applies to:** a Datasentinel platform that serves the `/mcp` endpoint with a **self-signed** certificate, or one issued by an **internal CA** the client host does not trust. Every assistant validates TLS certificates by default, so the connection is rejected before a single MCP tool can run.

{% hint style="info" %}
If your error message says **Hostname mismatch**, you are on the wrong page: the certificate is rejected because of its **name**, not its issuer. See [TLS hostname mismatch on API calls](/manual/ai-connector/troubleshooting/tls-hostname-mismatch.md) instead.
{% endhint %}

## Symptom

The `datasentinel-*` MCP server never appears in the assistant's server list, or shows as failed/disconnected. Depending on the client runtime, the underlying error looks like:

* **Node-based clients** (Claude Code, `mcp-remote`, VS Code, Cursor): `DEPTH_ZERO_SELF_SIGNED_CERT`, `SELF_SIGNED_CERT_IN_CHAIN`, or `UNABLE_TO_VERIFY_LEAF_SIGNATURE`.
* **Python-based clients** (custom agents): `[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:…)`.
* **Cloud-connecting assistants** (Claude custom connector, ChatGPT web, Copilot Studio): the connector simply fails to add or verify, with no local log to read.
* **The sign-in never starts.** The OAuth sign-in is the first thing the assistant's own HTTP client does: it fetches the discovery documents, registers itself, and later exchanges the code for tokens over HTTPS. With an untrusted certificate those calls fail before any login page opens, so an assistant that reports it cannot authenticate, or shows the server as needing authentication forever, is often showing a certificate problem. The browser that opens the login page must trust the certificate too, or it shows its own warning page.

To confirm the certificate is the cause, inspect what the platform actually serves:

```bash
openssl s_client -connect <public-host>:443 </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates
```

A self-signed certificate shows the **same** value for `subject` and `issuer`. An internal CA shows your organization's CA as the issuer.

## Three ways out, in order of preference

{% stepper %}
{% step %}

#### Serve a trusted certificate (recommended)

Using a valid TLS certificate is **highly recommended**, and it is the only option that works for every assistant at once. Provision one from a public authority such as Let's Encrypt, or issue one from your internal CA and install that CA in the trust store of every client host. Validation stays on everywhere, and every per-assistant workaround below becomes unnecessary.

See [MCP Server Setup](/manual/ai-connector/server-setup/mcp-server-setup.md) for where the certificate lives on the platform side.
{% endstep %}

{% step %}

#### Keep validation on, point the client at your CA

When replacing the certificate is not an option, the next best fix is to hand the client a PEM file containing your internal CA. The connection stays fully verified; the client just gains one extra trusted issuer. The variable to set depends on the client runtime: see the per-assistant table below.
{% endstep %}

{% step %}

#### Disable verification (last resort)

Some clients can skip certificate validation entirely. Treat this as a temporary measure for a quick local test, never as the lasting setup:

{% hint style="warning" %}
Bypasses like `NODE_TLS_REJECT_UNAUTHORIZED=0` disable certificate validation **process-wide**, for every TLS connection that process makes, not just the one to Datasentinel. The connection stays encrypted but the server is no longer authenticated. Several assistants (Codex, Antigravity, Mistral Vibe) offer **no** such switch at all, so a trusted certificate is the only path that works everywhere.
{% endhint %}
{% endstep %}
{% endstepper %}

## Per-assistant reference

Each cell shows the documented option; the guide linked in the first column carries the full context and caveats.

| Assistant                                                                                                                                                                                                | Keep validation on                                                                                                                                                                      | Disable verification (last resort)                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Claude Code](/manual/ai-connector/connect-a-cli-assistant/configure-claude-code.md)                                                                                                                     | `NODE_EXTRA_CA_CERTS=<path to PEM>` before launching, or the CA in the system trust store                                                                                               | `NODE_TLS_REJECT_UNAUTHORIZED=0 claude`                                                           |
| [Claude desktop (local bridge)](/manual/ai-connector/connect-a-desktop-app/configure-claude-desktop-windows.md)                                                                                          | `NODE_EXTRA_CA_CERTS` in the bridge's `env` block                                                                                                                                       | `"env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }` (scoped to the bridge process)                   |
| [Codex CLI](/manual/ai-connector/connect-a-cli-assistant/configure-codex-cli.md), [ChatGPT desktop app (ChatGPT and Codex)](/manual/ai-connector/connect-a-desktop-app/configure-chatgpt-desktop-app.md) | `CODEX_CA_CERTIFICATE=<path to PEM>` (falls back to `SSL_CERT_FILE`)                                                                                                                    | Not available                                                                                     |
| [GitHub Copilot CLI](/manual/ai-connector/connect-a-cli-assistant/configure-copilot-cli.md)                                                                                                              | Trust the CA in the system trust store                                                                                                                                                  | `NODE_TLS_REJECT_UNAUTHORIZED=0 copilot` (npm install only; the install-script binary ignores it) |
| [Google Antigravity CLI](/manual/ai-connector/connect-a-cli-assistant/configure-antigravity-cli.md)                                                                                                      | Trust the CA in the system trust store                                                                                                                                                  | Not available                                                                                     |
| [Mistral Vibe CLI](/manual/ai-connector/connect-a-cli-assistant/configure-mistral-vibe-cli.md)                                                                                                           | `SSL_CERT_FILE` pointing at the CA, or `enable_system_trust_store = true` in `config.toml` once the CA is in the system trust store; or front the endpoint with a trusted reverse proxy | Not available ([tracked upstream](https://github.com/mistralai/mistral-vibe/issues/30))           |
| [Visual Studio Code](/manual/ai-connector/connect-an-ide/configure-vscode.md)                                                                                                                            | System trust store (read via `http.systemCertificates`), or `NODE_EXTRA_CA_CERTS` before launching                                                                                      | `http.proxyStrictSSL: false` (not scoped to MCP)                                                  |
| [Cursor](/manual/ai-connector/connect-an-ide/configure-cursor.md)                                                                                                                                        | System trust store, or `NODE_EXTRA_CA_CERTS` before launching                                                                                                                           | `NODE_TLS_REJECT_UNAUTHORIZED=0 cursor` (recent versions may ignore it)                           |
| [Custom Python agents](/manual/ai-connector/developers/build-a-python-agent-with-deepagents.md)                                                                                                          | `SSL_CERT_FILE=<path to PEM>`                                                                                                                                                           | `verify=False` on the `httpx` client (as in the worked example, test setup only)                  |

## Cloud-connecting assistants have no workaround

Claude's **custom connector**, **ChatGPT on the web**, and **Microsoft Copilot Studio** connect to your platform from the vendor's cloud, not from your machine. For these, the `/mcp` endpoint and the sign-in endpoints on the same host must be reachable from the public internet **with a valid, publicly-trusted certificate**: there is no trust store you can edit and no bypass variable.

With a self-signed or internal-CA certificate, use a path that runs closer to the platform instead:

* the [local bridge method](/manual/ai-connector/connect-a-desktop-app/configure-claude-desktop-windows.md) for the Claude desktop app;
* a locally-running tool such as [Visual Studio Code](/manual/ai-connector/connect-an-ide/configure-vscode.md) in place of Copilot Studio.

## Trusting an internal CA at the host level

For the "system trust store" rows above, install your CA certificate on the client host:

{% tabs %}
{% tab title="Debian / Ubuntu" %}

```bash
sudo cp internal-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

The file must have a `.crt` extension and contain a PEM-encoded certificate.
{% endtab %}

{% tab title="RHEL / Rocky / Fedora" %}

```bash
sudo cp internal-ca.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
```

{% endtab %}

{% tab title="Windows" %}
From an elevated PowerShell:

```powershell
Import-Certificate -FilePath C:\path\to\internal-ca.pem -CertStoreLocation Cert:\LocalMachine\Root
```

Restart the assistant afterwards so it re-reads the store.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Node-based clients do **not** all read the operating-system store automatically; that is what `NODE_EXTRA_CA_CERTS` is for. When in doubt, set both: install the CA system-wide and export `NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem` before launching the assistant.
{% endhint %}

## Verifying the fix

From the client host, a plain `curl` call with verification **on** must succeed before the assistant will connect:

```bash
curl -s -o /dev/null -w '%{http_code}\n' https://<public-host>/mcp
```

`406` (Not Acceptable) means healthy: the endpoint answered and TLS verification passed. If you still need `-k` to get an answer, the trust problem is still there.

Then reconnect from the assistant and run `datasentinel status` to confirm the MCP tools return live data.

{% hint style="success" %}
Just want to evaluate AI Connector without touching certificates? The [sandbox platform](/manual/ai-connector/test-with-the-sandbox-platform.md) is served with a valid public certificate, so every connection method works against it out of the box.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.datasentinel.io/manual/ai-connector/troubleshooting/ssl-certificates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.