12. Troubleshooting
 
Connection and authentication issues
Configuration and rights issues
Execution and performance issues
Support information
Use the checks below to diagnose common connection, authentication, configuration, rights, execution, and supervision issues.
12.1. Connection and authentication issues
*Check the HTTPS URL of the MCP Server.
*Check network access from the AI client.
*Check the TLS certificate, proxy, or gateway.
*With OAuth/DCR, check the authentication flow and the token.
*With API key mode, check server-side authorization and the x-api-key header.
For local usage, connection issues may occur when the AI client relies on Node.js and Node.js does not trust the certificate chain. In that case, set the NODE_OPTIONS environment variable to --use-system-ca so that Node.js uses the Windows certificate store.
12.2. Configuration and rights issues
*Check the headers configured in the AI client: x-schema, x-api-key, x-allow-mutation.
*Check the default GraphQL schema in the HAS console.
*Check the connection profile, Hopex rights, and the customized metamodel exposure described in section 5.2 Customized metamodel exposure when a custom schema is used.
*Confirm the exact header syntax in the AI client documentation.
12.3. Execution and performance issues
*Check GraphQL errors returned by the MCP Server.
*For mutations, check the configuration described in section 5.1.2 Mutation authorization.
*For deletions, check the explicit confirmation request.
*In case of latency, reduce the requested volume, explored relationships, or query depth.
12.4. Support information
*MCP Server URL and environment.
*AI client used, version, and connection mode.
*Authentication mode.
*Configured headers.
*GraphQL schema used.
*MCP session / mcpSessionId.
*Tool or resource concerned.
*Structured response returned.
*HAS supervision events.
*Client-side and server-side logs, when available.