Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| "Server not found" error | Ensure Node.js 22+ is installed and npx is available in your PATH |
| Authentication failures | Verify your API key is correct and has not expired |
| Connection timeout | Check your network connection and firewall settings |
| "Permission denied" errors | Confirm your API key has the required scopes for the action |
| Server crashes on startup | Run npx -y @kula-ai/mcp-server directly in your terminal to see error output |
| Tools not appearing | Restart your AI client after updating the configuration file |
Debugging Tips
Run the server directly
To see detailed error output, run the MCP server outside of your AI client:
KULA_API_KEY="your_api_key_here" npx -y @kula-ai/mcp-server
This will show startup logs and any errors that may be hidden when running through an AI client.
Check your Node.js version
node --version
The Kula MCP server requires Node.js 22 or later.
Verify your API key
Make a direct API call to confirm your key is valid:
curl -H "Authorization: Bearer your_api_key_here" \
https://api.kula.ai/api/v1/departments
A 200 response confirms your key is working. See Authentication for more details.
Reinstall the package
If you're seeing stale behavior after an update, clear the npx cache:
npx -y @kula-ai/mcp-server@latest