Troubleshooting BigFix Platform MCP Server

VSCode returns "TypeError: fetch failed" on MCP client startup

A fetch failure when connecting to https://<mcp-host>:9494 is commonly caused by listener certificate name mismatch or missing certificate trust in the environment where VS Code opens the MCP connection.

A self-signed certificate works only when both conditions are met:
  • The MCP URL uses a hostname or IP address present in the certificate Subject Alternative Name.
  • The certificate or its issuing CA is trusted by the operating-system environment where the MCP client runs.
When HTTPS is enabled and no custom listener certificate is configured, the MCP Server generates a self signed certificate. The generated certificate includes localhost and 127.0.0.1 and can include the configured mcp_server.server value.
  1. Use an MCP URL that matches the certificate, such as localhost, 127.0.0.1, or the configured host/IP included in the SAN.
  2. Trust the certificate in the correct operating-system trust store.
  3. Reload VS Code or restart the remote extension host after adding trust.
  4. If the service regenerated the certificate, trust the new certificate because its fingerprint changed.
  5. For Remote SSH, WSL, Codespaces, or development containers, install trust in the remote environment rather than only on the local workstation.

HTTP alternative: HTTP avoids certificate validation but provides no encryption or server identity validation. Use it only for local development or tightly controlled internal environments.

Example 1: HTTPS with a self-signed listener certificate

mcp_server: 
  scheme: "https" 
  server: "10.X.X.X" 
  port: "9494" 
  read_only: true 
  disable_hitl: false 
 
bigfix: 
  url: "https://my-bigfix-server:52315" 
  ca_cert_path: "C:/path/to/root-server-ca.crt" 
 
log: 
  file_path: "C:/Program Files/BigFix Enterprise/BES MCP Server/BESMCPServer.log" 
{ 
  "servers": { 
    "bigfixMcp": { 
      "type": "http", 
      "url": "https://10.X.X.X:9494", 
      "headers": { 
        "Authorization": "Bearer ${input:bigfix-token}", 
        "X-Bes-Mcp-Read-Only": "true", 
        "X-Bes-Mcp-Disable-Hitl": "false" 
      } 
    } 
  }, 
  "inputs": [ 
    { 
      "type": "promptString", 
      "id": "bigfix-token", 
      "description": "BigFix REST API token", 
      "password": true 
    } 
  ] 
}

Example 2: HTTPS with a custom listener certificate

mcp_server: 
  scheme: "https" 
  server: "mcp-server.example.com" 
  port: "9494" 
  read_only: true 
  disable_hitl: false 
  tls: 
    cert_path: "C:/Program Files/BigFix Enterprise/BES MCP Server/certs/server.crt" 
    key_path: "C:/Program Files/BigFix Enterprise/BES MCP Server/certs/server.key" 
 
bigfix: 
  url: "https://my-bigfix-server:52315" 
  ca_cert_path: "C:/path/to/root-server-ca.crt" 
 
log: 
  file_path: "C:/Program Files/BigFix Enterprise/BES MCP Server/BESMCPServer.log"

Example 3: HTTP without TLS

mcp_server: 
  scheme: "http" 
  server: "10.X.X.X" 
  port: "9494" 
  read_only: true 
  disable_hitl: false 
 
bigfix: 
  url: "https://my-bigfix-server:52315" 
  ca_cert_path: "C:/path/to/root-server-ca.crt" 
 
log: 
  file_path: "C:/Program Files/BigFix Enterprise/BES MCP Server/BESMCPServer.log"

No listener TLS: No certificate trust is required for the client-to-MCP connection, but traffic is not encrypted and the client cannot validate the identity of the MCP Server.

Log evidence examples

2026-07-31 15:22:55.359 [info] Connection state: Running
2026-07-31 15:22:55.459 [info] Connection state: Error 
Error sending message to https://mcp-server-ip:9494/: TypeError: fetch failed
2026-07-31 15:23:36.944 [info] Stopping server bes-mcp-server

Symptom: Client fails to establish the connection or trust the listener certificate.

Solution: Inspect the listener certificate and ensure its Subject Alternative Name (SAN) exactly matches the configured MCP URL. Trust the certificate in the local or remote OS environment where the VS Code extension host is running, then reload the window. Alternatively you can use the http mode if https is not strictly required.

Note: This refers to an AI Client VSCode Output log error.

Fri, 31 Jul 2026 15:24:11 +0200|INFO||MCP|TOOL|AUTH_FAILURE|10.14.85.112|Authentication failure 
[auth_fingerprint v1:cb726c3527c3c35e error 
"failed to create BigFix client: failed to read CA cert file from 
C:/Program Files (x86)/BigFix Enterprise/BES MCP Server/data/ca2.crt: 
open C:/Program Files (x86)/BigFix Enterprise/BES MCP Server/data/ca2.crt: The system cannot find the file specified."

Symptom: The client connects, but the MCP Server cannot validate the upstream Root Server TLS certificate or path.

Solution: Verify the path specified in bigfix.ca_cert_path within the config.yaml file. Ensure the file exists, contains the correct Root CA, and is readable by the unprivileged service account. Restart the service to apply changes.

Note: This refers to an audit log error.

Fri, 31 Jul 2026 15:26:34 +0200 -- 6032 -- ListenAndServeTLS 
[error="tls: found a certificate rather than a key in the PEM for the private key"]

Symptom: The MCP Server service fails to bind the port or load the listener TLS material.

Solution: Open config.yaml and verify the mcp_server.tls block. Ensure that key_path points to a valid private key file and the cert_path points to a valid certificate. Restart the bes-mcp-server service to apply the fix.

Note: This refers to an BESMCPServer.log error.