Connection troubleshooting

Most problems connecting an AI client to Novamira come down to a handful of causes. This page lists them with the most common first. Each one gives the symptom, why it happens, and the fix. It applies to both Novamira and Novamira Pro. For Pro license and update issues, see Troubleshooting Pro.

Windows: TLS or certificate errors

Symptom. On Windows the connection fails with a TLS or certificate error, often UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN, or unable to get local issuer certificate.

Why it happens. The connection runs through Node.js, which ships with its own fixed list of trusted certificate authorities. On many Windows machines a corporate proxy or an antivirus that inspects HTTPS traffic re-signs the connection with a certificate that is trusted by Windows but not in that bundled list, so Node.js rejects it.

Fix. Find the Novamira server entry that is already in your client config and add NODE_OPTIONS to its env block, so Node.js trusts the certificates in the Windows system store. The Connect page names that server for you, usually something like novamira-yoursite (the exact name varies from site to site), so edit the entry you already have rather than adding a new one. A complete entry looks like this:

{
  "mcpServers": {
    "novamira-yoursite": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/novamira",
        "WP_API_USERNAME": "your-wordpress-username",
        "WP_API_PASSWORD": "your-application-password",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

Keep whatever name your config already uses for the server, do not rename it to novamira. Only the NODE_OPTIONS line needs to be added.

Already have other MCP servers? Do not replace the whole file. Add or edit the Novamira entry inside your existing mcpServers block, next to the servers you already have, and put a comma between each server:

"mcpServers": {
  "your-other-server": {
    ...
  },
  "novamira-yoursite": {
    "command": "npx",
    "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
    "env": {
      "WP_API_URL": "https://your-site.com/wp-json/mcp/novamira",
      "WP_API_USERNAME": "your-wordpress-username",
      "WP_API_PASSWORD": "your-application-password",
      "NODE_OPTIONS": "--use-system-ca"
    }
  }
}

Watch the commas. Inside the env block every line ends with a comma except the last one, which here is NODE_OPTIONS. Between servers, every entry ends with a comma except the last one. A misplaced or missing comma breaks the whole file, and it is the most common mistake.

Save the config and restart your AI client. This uses the Windows certificate store instead of the one bundled with Node.js, which resolves connections broken by corporate proxies or HTTPS-inspecting antivirus.

Claude Desktop one-click bundle won’t connect

Symptom. You installed the one-click .mcp bundle in Claude Desktop and Novamira never connects or shows no tools.

Why it happens. The one-click bundle is temporarily unavailable: it does not connect correctly on recent Claude Desktop versions, so we removed it for now while we work on a fix.

Fix. Connect Claude Desktop with the manual configuration instead. Follow Connecting Your AI Client and use the setup prompt or the ready-made claude_desktop_config.json snippet. It works the same way, it just takes one extra step.

“Application Passwords require HTTPS”

Symptom. WordPress won’t let you create an application password and shows a message that HTTPS is required.

Why it happens. For security, WordPress only enables application passwords when the site is served over HTTPS, or when it is explicitly marked as a local environment.

Fix. Use HTTPS on your site. If you are working on a local site that genuinely runs without HTTPS, mark the environment as local by adding this to wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' );

Connection refused

Symptom. The client reaches your site but the MCP connection is refused.

Why it happens. AI abilities are turned off, so Novamira is not exposing the MCP endpoint.

Fix. Open Novamira > Configuration in the WordPress admin and make sure AI abilities are enabled.

Authentication failed

Symptom. The connection is rejected with an authentication or 401 error.

Why it happens. The username or application password in the config is wrong. The username is case-sensitive, and a copied password can pick up a stray space.

Fix. Double-check the WordPress username and application password. If in doubt, create a fresh application password in Novamira > Configuration and paste it again.

“npx: command not found”

Symptom. Starting the client fails with npx: command not found.

Why it happens. The standard configuration runs the connection through npx, which comes with Node.js. Node.js is not installed or not on your PATH.

Fix. Install Node.js, then restart your terminal and client. See Installing Node.js. If your IT policy blocks npx, use the npx-free direct HTTP option described in Connecting Your AI Client.

Tools not showing up

Symptom. The connection succeeds but you don’t see the Novamira tools in your client.

Why it happens. Many clients only load MCP servers at startup, so a config added mid-session isn’t picked up.

Fix. Fully restart your AI client after adding or changing the MCP configuration, then start a new session.

Still stuck

If none of the above resolves it, ask in the Novamira community, where the team and other users can help. On Novamira Pro you also get direct help from the Dynamic.ooo team through the support page.