Generation issues
”Spec validation failed”
Your OpenAPI spec has structural issues. Run the Validation check to see specific errors. Common causes:- Missing
pathsorinfofields - Broken
$refreferences pointing to non-existent schemas - Invalid OpenAPI version identifier
Generation succeeds but some operations are missing
Operations may be skipped if they:- Have no defined HTTP method
- Have duplicate operation IDs (the second is renamed with a
_2suffix) - Reference undefined schemas that can’t be resolved
Runtime issues
”ModuleNotFoundError”
Dependencies aren’t installed. Run:”Connection refused” or timeout errors
The target API is unreachable. Check:BASE_URLin.envis correct- Your network can reach the API (try
curlor a browser) - The API isn’t rate-limiting you (check for HTTP 429 responses in logs)
OAuth2 authorization fails
- Ensure
OAUTH2_CLIENT_IDandOAUTH2_CLIENT_SECRETare correct - Check that port 8090 (callback port) is available
- Some APIs require pre-registered redirect URIs — add
http://localhost:8090/callbackto your app’s OAuth settings - Delete
oauth2_tokens.jsonand try again
”Rate limit exceeded”
The server’s local rate limiter is blocking requests. Increase the limit:.env
Circuit breaker is open
The target API has been failing consistently. The circuit breaker blocks requests to prevent cascading failures. Wait for the timeout period (default 60 seconds) or restart the server to reset the circuit breaker state.MCP client issues
Tools don’t appear in your MCP client
See Connecting to AI Agents — Troubleshooting.Tools appear but return errors
Runpython server.py directly in a terminal to see detailed error output. Common causes:
- Missing or incorrect credentials in
.env - API returning unexpected response format
- Network issues between your machine and the API