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
Pass --profile <name> to scope to a specific profile. Pass --client <name> to mcp verify to inspect a specific AI client's config.
Your shell can't find the binary on PATH.
$
which kuali # nothing? it's not on PATH
$
ls /usr/local/bin/kuali ~/.local/bin/kuali 2>/dev/null
$
where.exe kuali
$
Get-Item "$env:LOCALAPPDATA\Programs\kuali\kuali.exe"
If the file exists but isn't on PATH, add the containing directory to PATH in your shell config (~/.zshrc, ~/.bashrc):
$
export PATH="$HOME/.local/bin:$PATH"
Then source the file or open a new terminal.
Open a new PowerShell window — the one you installed in doesn't inherit the updated PATH. Still missing?
>
where.exe kuali
>
Get-Item "$env:LOCALAPPDATA\Programs\kuali\kuali.exe"
If the file exists, reopen PowerShell or sign out and back in so the new PATH entry takes effect.
"kuali cannot be opened because the developer cannot be verified"
macOS quarantines any executable downloaded from the web. Clear the flag:
$
xattr -d com.apple.quarantine $(which kuali)
Or go through the GUI: System Settings → Privacy & Security, scroll to Security, and click Allow Anyway next to the Connector entry.
On first launch you'll see "Windows protected your PC". Click More info, then Run anyway. One-time; won't repeat.
$
kuali auth status --profile yourschool # shows resolved URL + masked key
$
kuali doctor --profile yourschool # verifies auth end-to-end
The API key is wrong, expired, or scoped to a different profile than the command is using. Common causes:
Wrong profile. kuali auth status without --profile shows the default profile. Pass --profile to see a specific one.
Key was revoked. Go to the Kuali web UI, Settings → API Keys, and check. Create a new one and re-run kuali setup --profile yourschool --force (or kuali auth login --profile yourschool if the URL is already correct).
KUALI_API_KEY set in the environment. A plain KUALI_API_KEY takes priority over every profile. Run env | grep KUALI to check; unset it and try again.
Error: dial tcp: ... or x509: certificate signed by unknown authority
Typo in the URL? kuali config get api_url --profile yourschool — compare to what you see when you log into the web UI.
VPN or firewall? Try reaching it from a browser on the same machine. If the browser works and the Connector doesn't, check for a proxy set via HTTPS_PROXY.
Self-signed cert on a local instance? Set insecure: true on the profile: kuali config set insecure true --profile local, or pass -k per command. Don't enable this against a production instance.
Run the diagnostic first — it'll tell you exactly which piece is wrong:
$
kuali mcp verify # default: Claude Desktop
$
kuali mcp verify --client claude-code
$
kuali mcp verify --client codex
It checks five things: the client's MCP config file exists and parses, a kuali entry is registered, the binary path resolves and is executable (with a macOS quarantine-flag check), the API key resolves for the referenced profile, and the binary can run (kuali version).
Test the server outside the AI client:
$
kuali mcp 2>&1 | head -5
The process should stay running and print nothing to stdout (MCP uses stdio, so stdout is reserved for protocol messages). If it exits immediately with an error, read the stderr line — auth and config issues show up here first.
MCP clients cache the server config. Rerun setup, then restart the client:
$
kuali mcp setup --profile yourschool
For Claude Desktop, that means Cmd+Q and reopen — not just closing the window.
Check which tools are registered:
$
kuali mcp 2>&1 &
$
sleep 1
$
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | kuali mcp
If expected tools are missing, you may have enabled read-only mode. kuali mcp verify shows the args array — look for --tools read-only.
Priority order for URL and API key resolution:
--api-key / --profile flag on the command
KUALI_API_KEY / KUALI_API_URL env vars (global — set these with care)
KUALI_<PROFILE>_API_KEY / KUALI_<PROFILE>_API_URL env vars
OS keychain (from kuali auth login)
~/.kuali/credentials
api_key field in ~/.kuali/config.yaml
If a wrong profile is being chosen, it's almost always because a global KUALI_API_KEY or KUALI_API_URL is set and stomping on per-profile values. Unset it:
$
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
Then file an issue and attach the outputs. Redact the api_key field if any shows up (it shouldn't — doctor masks it by default).
Last updated: September 21, 2026
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 →