This topic describes common error symptoms, their likely causes, and recommended fixes. Use these remedies to quickly resolve issues during MCP operations.
Symptom Likely cause Fix
Specification file not found The path is incorrect, or the volume is missing. Re-run the up command with the correct --spec option.
Authentication failures (401) The service account header is missing. Include the X-OEMCP-SERVICEACCOUNT header with a valid JWT token.
Tools list is empty Scopes are filtering out all the tools. Add the required scopes or adjust security.authorization.tools.
Token not found with --sa-token The specified token name does not exist. Check available tokens using ./mcpgen sa-tokens <profile_name>.
Wrong token used despite flag An environment variable is overriding the token. Unset $SERVICE_ACCOUNT_JWT or use the explicit --sa-token parameter.
Admin tools not visible A regular token is being used. Use --sa-token admin or a token with the mcp_admin scope.
Missing TLS despite config Certificates or key files are not present. Ensure that both the certificate file and the key file are present. For development environments, run the certificate generation script to create these files.
SA header double prefix The manual prefix was added to the token file. Allow the generator to build the header; avoid manual prefixing.
Empty prompt plan --no-prompt was used, or no prompt files exist. Remove the flag or add prompt .md files.
Token exchange timeout Incorrect URL or network issue. Validate that the exchange endpoint is reachable from the container.