This section describes common issues that may occur when using the MCP tools and provides guidance on diagnosing and fixing them. Use this information to troubleshoot errors quickly and maintain smooth operations.

The following table lists symptoms, possible diagnoses, and recommended fixes:
Symptom Diagnosis Fix
401 Missing service account Service account required but header is absent or invalid Add X-OEMCP-SERVICEACCOUNT header with a valid JWT token
Empty tool list Scope filtering or authentication mismatch Ensure authentication is enabled and token has required scopes. Disable filtering if necessary
Large array rejection Response guard blocked large arrays Increase max_array_items or switch to pagination
TLS handshake failure Incorrect certificate or key path, or client trust store Recreate certificates using --tls option and verify file permissions
Certificate hostname mismatch Client accessing server with a hostname not in certificate Use --extra-hostnames to include all expected domains in the certificate
Export bundle missing files Wrong bundle type or corrupted export Check --bundle type. Use dev for full artifacts and prod for production bundles
Service account token not found Named token does not exist or incorrect name Use ./mcpgen sa-tokens <profile> to list available tokens
OpenAPI generation failed Invalid catalog source or network issue Verify catalog file or URL accessibility and format
Token exchange timeout Exchange URL unreachable Check network connectivity and ensure container can resolve the host
High latency on first call JWKS fetch delay Warm up cache by invoking a simple tool at startup
Unclear HTTP errors or authentication issues Lack of detailed request or response information Use ./mcpgen client <profile> --debug to view HTTP details
Tool invocation fails with Internal error. The server encountered an internal failure and cannot complete the tool call. Review the server log files to identify the cause. Run the following command: 
docker compose -f docker-compose.mcp.yml logs -f --tail=50
Smoke test fails when running ./mcpgen up or ./mcpgen restart. For example, call_tool fails with error Internal error. The automated smoke test is unable to validate tool access during startup or restart. Do not ignore smoke test failures. Investigate the cause before bypassing the smoke test. After investigating, if you have confirmed a valid reason for the failure, such as a timeout, or are unable to determine the cause, you may proceed with the following workaround:
  1. Rerun ./mcpgen up or ./mcpgen restart with the --no-smoke option, for example:
    ./mcpgen up --no-smoke
    		 
    ./mcpgen restart --no-smoke <container_name>
  2. Manually call a tool to verify access:
    ./mcpgen client --tool <tool_name> --json <profile>
    If this call fails, such as with an Internal error, see the corresponding entry in this table.