When something's off, start here. Two diagnostics catch most issues — kuali doctor for config, URL, auth, and API reachability; kuali mcp verify for MCP client config, binary path, and permissions.
$
kuali doctor # config, URL, auth, API reachability
$
kuali mcp verify # MCP client config, binary path, permissions
$
which kuali # nothing? it's not on PATH
$
export PATH="$HOME/.local/bin:$PATH"
If the file exists but isn't on PATH, add the containing directory to PATH in your shell config, then open a new terminal.
$
xattr -d com.apple.quarantine $(which kuali)
Or System Settings → Privacy & Security → Allow Anyway. On Windows, click More info → Run anyway — one-time, won't repeat.
$
kuali auth status --profile yourschool
$
kuali doctor --profile yourschool
Common causes: the wrong profile is active, the key was revoked (create a new one and re-run kuali setup --force), or a global KUALI_API_KEY env var is stomping on per-profile values — run env | grep KUALI and unset it.
Typo in the URL? Compare kuali config get api_url to the address you sign in at. VPN or firewall? Try the URL in a browser on the same machine. Self-signed cert on a local instance? Set insecure: true on that profile — never on production.
$
kuali mcp verify --client claude-code
✓ config parses ✓ entry ✓ binary ✓ key resolves ✓ runnable
Changed your API key and the assistant still fails? MCP clients cache the server config — rerun kuali mcp setup, then fully quit and reopen the client. Tools missing? You may be in read-only mode — verify shows the args array.
Resolution priority: command flags, then global KUALI_API_KEY / KUALI_API_URL env vars, then per-profile env vars, then the OS keychain, then ~/.kuali/credentials. A stray global env var is almost always the culprit:
$
unset KUALI_API_KEY KUALI_API_URL
$
kuali doctor --profile yourschool -o json > kuali-doctor.json
$
kuali mcp verify > kuali-mcp-verify.txt 2>&1
$
kuali version
Attach the outputs to an issue — doctor masks your API key by default.
ON THIS PAGE
kuali doctor and kuali mcp verify pinpoint the failing piece before you touch anything.
Run kuali doctor ->
Ready-to-use prompts for curriculum, research, build apps, imports, workflow analysis, and reporting.
Browse prompts →
Tips for Claude Desktop, Claude Code, Codex, Gemini, Copilot, and VS Code.
AI assistants →
Skip the chat — every capability is also a plain kuali command, ready for scripts and CI.
Command reference →
