Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
command not found: userintuition-mcp

The binary isn’t on your PATH. Pick the install style you used and verify: 
npm install -g @userintuition-ai/mcp
which userintuition-mcp     # should print a path
If which is empty, your global npm bin directory isn’t on PATH. Run npm config get prefix and add <prefix>/bin to PATH.

​
No authentication found

{"error":"No authentication found. Set USERINTUITION_API_KEY environment variable …"}
The CLI couldn’t read USERINTUITION_API_KEY from its environment. Common causes:
  1. Not exported in the current shell. 
    export USERINTUITION_API_KEY=ui_sk_...
userintuition-mcp call list_studies
  2. Set in ~/.zshrc but the shell didn’t reload. Open a new terminal or source ~/.zshrc.
  3. Running under sudo or a different user. sudo strips most env vars — prefix the call: sudo USERINTUITION_API_KEY=ui_sk_... userintuition-mcp call …
  4. CI secret not wired. Confirm the variable is set as a secret in your CI provider and exposed to the step that runs the CLI.

​
401 Unauthorized from the backend

The key is read but the backend rejected it.
  • Revoked or rotated. Generate a new key at app.userintuition.ai → Settings → API Keys and update your environment.
  • Wrong environment. Production keys (ui_sk_live_...) don’t work against staging and vice versa. Check BACKEND_URL if you’ve overridden it.
  • Typo / wrapping whitespace. echo "$USERINTUITION_API_KEY" | wc -c — should match expected key length (no trailing newline issues).

​
Invalid input for <tool>: …

Zod schema validation failed before the CLI tried to call the backend. The error message names the offending field. 
$ userintuition-mcp call ask_humans --mode bogus --text x
Invalid input for ask_humans: Invalid enum value. Expected 'preference' | 'claim' | 'message', received 'bogus'
Re-read the schema: 
userintuition-mcp describe ask_humans
Common variants:
  • Missing required flag. Add it.
  • String where a number/boolean/array is expected. Make sure the value is JSON-parseable: --n 25 not --n "twenty-five"; --options '["A","B"]' not --options A,B.
  • Nested objects. Use --input-json rather than flags.

​
Tool call hangs or times out

Network egress to api.userintuition.ai may be blocked or slow. 
curl -sS -w "%{http_code}\n" -o /dev/null https://api.userintuition.ai/health
# Expect 200
If the curl works but the CLI hangs, the tool may legitimately be long-running (e.g. generate_powerpoint). Check the equivalent operation in the dashboard — if it normally takes minutes, the CLI behaves the same way. If you’re on a corporate network, confirm a proxy hasn’t TLS-intercepted the connection. Node respects HTTPS_PROXY; set it explicitly if needed.

​
EACCES / permission denied on the binary

After a manual tsc build, dist/index.js may not be executable. 
chmod +x ./dist/index.js
npm publish handles this automatically — only a concern for local builds.

​
Output isn’t valid JSON

The CLI writes the tool’s text response verbatim to stdout. Most tools return JSON; a few (e.g. PowerPoint generation) return a URL or status string. Use userintuition-mcp describe <tool> to confirm the response shape, and check whether the tool returned an {"error": …} envelope on a logical failure. If stderr contents are being mixed into your pipe, redirect them out: userintuition-mcp call … 2>/dev/null | jq ..

​
Still stuck?

Run the equivalent MCP call through the official inspector to isolate whether the issue is the CLI or the underlying tool: 
npx @modelcontextprotocol/inspector npx -y @userintuition-ai/mcp
If it reproduces there, the bug is in the tool or the backend — open an issue at github.com/userintuition. If it only reproduces in the CLI, please include the exact command, your CLI version (npm ls -g @userintuition-ai/mcp), and Node version (node --version).