> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-in-ai/mcp/connect-to-an-mcp-server/local-mcp-setup/tls-certificates.md).

# TLS Certificates

Connect an Umbraco MCP server to a local Umbraco with a self-signed certificate, and why NODE\_TLS\_REJECT\_UNAUTHORIZED is for local sites only.

A local Umbraco site serves HTTPS with the .NET development certificate. Node.js runs the MCP server and doesn't trust that certificate. Without extra configuration, requests from the MCP server to Umbraco fail with a certificate error such as `DEPTH_ZERO_SELF_SIGNED_CERT`.

You can solve this in two ways:

| Setting                          | Certificate verification | Use with                                         |
| -------------------------------- | ------------------------ | ------------------------------------------------ |
| `NODE_TLS_REJECT_UNAUTHORIZED=0` | Off                      | A local Umbraco only                             |
| `NODE_EXTRA_CA_CERTS`            | On                       | Any site whose certificate Node.js doesn't trust |

The [Local MCP Setup](https://docs.umbraco.com/umbraco-in-ai/mcp/connect-to-an-mcp-server/local-mcp-setup.md) examples use `NODE_TLS_REJECT_UNAUTHORIZED=0`, the quickest option for a local site.

## Use NODE\_TLS\_REJECT\_UNAUTHORIZED for a Local Umbraco Only

Setting `NODE_TLS_REJECT_UNAUTHORIZED` to `0` turns off certificate verification for every HTTPS request the MCP server makes. The setting applies to the whole process, not only to requests to Umbraco.

When Umbraco runs on your own machine, the traffic between the MCP server and Umbraco stays on that machine. Over a network, anyone who can intercept the traffic could impersonate the site, for example on shared Wi-Fi. The MCP server would then send them the API user's client ID and secret.

### Remote Connections Are Refused

An Umbraco MCP server refuses to start when `NODE_TLS_REJECT_UNAUTHORIZED` is `0` and `UMBRACO_BASE_URL` isn't local. The server writes an error and exits before it requests an access token. The client secret is never sent over an unverified connection. No setting overrides this check.

The server treats `UMBRACO_BASE_URL` as local only when its hostname is exactly one of the following:

* `localhost`
* `127.0.0.1`
* `[::1]`

Any other hostname counts as remote. This includes names that point to your own machine or network, such as `mysite.local`, hosts-file aliases, `host.docker.internal`, and IP addresses on your local network. For these hosts, use `NODE_EXTRA_CA_CERTS`, described below.

If the MCP server stops starting after you change `UMBRACO_BASE_URL`, check whether `NODE_TLS_REJECT_UNAUTHORIZED` is still set. The error appears in your MCP client's log for the server.

{% hint style="info" %}
The check applies to Umbraco MCP servers built on version `1.0.0-beta.47` or later of the MCP Server SDK. These package versions include it:

* Developer MCP Server: 18.1.10
* Forms MCP Server: 18.2.1-beta.3
* Automate MCP Server: 18.0.0-beta.4
  {% endhint %}

## Connect to a Remote Umbraco

Remove `NODE_TLS_REJECT_UNAUTHORIZED` from the server's configuration. A site with a certificate from a public certificate authority needs no TLS setting.

If the site uses a self-signed or internal certificate, use `NODE_EXTRA_CA_CERTS`.

## Keep Verification On with NODE\_EXTRA\_CA\_CERTS

`NODE_EXTRA_CA_CERTS` adds certificates to the set that Node.js trusts. Certificate verification stays on, so the MCP server still rejects any certificate you haven't trusted.

1. Export the .NET development certificate as a `.pem` file:

   ```bash
   dotnet dev-certs https --export-path ./dev-cert.pem --format Pem
   ```

   The command exports the certificate only, without its private key.
2. Set `NODE_EXTRA_CA_CERTS` to the full path of the file in the server's `env`. Use it instead of `NODE_TLS_REJECT_UNAUTHORIZED`:

   ```json
   {
     "mcpServers": {
       "umbraco-mcp": {
         "command": "npx",
         "args": ["@umbraco-cms/mcp-dev@latest"],
         "env": {
           "NODE_EXTRA_CA_CERTS": "/full/path/to/dev-cert.pem",
           "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
           "UMBRACO_CLIENT_SECRET": "1234567890",
           "UMBRACO_BASE_URL": "https://localhost:12345"
         }
       }
     }
   }
   ```
3. Restart the MCP server.

Set `NODE_EXTRA_CA_CERTS` in your MCP client's configuration, not in a `.env` file. Node.js reads it when the process starts, before the MCP server loads `.env`.

The certificate only covers the hostnames listed in it. Recent versions of the .NET development certificate include `host.docker.internal` as well as `localhost`, `127.0.0.1` and `[::1]`.

For a site with its own certificate, export that certificate, or the certificate of the authority that issued it, as a `.pem` file. Then use it in the same way.

If you regenerate the development certificate, for example after it expires, export it again.


---

# 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.umbraco.com/umbraco-in-ai/mcp/connect-to-an-mcp-server/local-mcp-setup/tls-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.
