UserDelphi MCP server

Order user-research studies and read insights from inside Claude Code (or any MCP client). It wraps the UserDelphi REST API — the magic loop:

"I just deployed this preview — run a study on it and tell me what's broken."

Tools

| Tool | What it does | |------|--------------| | connect / connect_poll | Link this editor to your workspace via a browser approval — no key to copy. | | launch_study | Order a prototype-feedback study (name, prototype_url, questions, participants, mode). Returns study_id, share_url, report_url. | | instant_feedback | Run (or add more) AI-persona feedback on an existing study, now. | | list_studies | List your studies with status + report URLs. | | get_study_report | The synthesised insight (the one thing to do, top issues, themes) + per-session analyses. |

Two modes

• mode: "live" (default) — real people. Recruiting is handled separately (a panel / your internal test pool); you get a share_url to put in front of testers and poll report_url as sessions land.
• mode: "instant" — a panel of AI personas explores the prototype right now, thinks aloud, and answers your questions. The report is populated before launch_study returns (~a minute). It's a directional preview, clearly labelled synthetic — not a substitute for real users. Great for a first read before you spend real testers. The report's counts break out synthetic_sessions vs real_sessions, and each session has is_synthetic.

You can mix both: launch instant for an immediate read, then share the same share_url to layer real human sessions onto the same report.

Setup (zero-config)

Nothing to clone or install — it runs straight from npm via npx. No key to copy.

1. Add it to Claude Code (no UD_API_KEY):

   claude mcp add userdelphi -s user \
     --env UD_BASE_URL=https://your-userdelphi-app \
     -- npx -y userdelphi-mcp

   For local dev, UD_BASE_URL=http://localhost:3000. -s user registers it for all your projects.

   Cursor / Codex (mcp.json):

   {
     "mcpServers": {
       "userdelphi": {
         "command": "npx",
         "args": ["-y", "userdelphi-mcp"],
         "env": { "UD_BASE_URL": "https://your-userdelphi-app" }
       }
     }
   }

2. Connect from the editor. Ask the agent:

   "Connect to UserDelphi."

   It runs the connect tool, which prints a short code and a URL. Open the URL, sign in, approve the code — the key is minted and saved to ~/.userdelphi/credentials.json. The agent calls connect_poll to finish. Done; every other tool now works.

   Prefer a terminal? npx -y -p userdelphi-mcp userdelphi-connect (set UD_BASE_URL first).

Or set a key explicitly

If you'd rather manage the key yourself: in the app, Settings → API keys → create one (ud_live_..., shown once), then pass it as --env UD_API_KEY=ud_live_xxxxx (or in ~/.claude.json / a project .mcp.json). An explicit UD_API_KEY always takes precedence over a saved one.

From source (contributors)

Working on the server itself? Run it from the repo instead of npm:

cd mcp && npm install
claude mcp add userdelphi -s user \
  --env UD_BASE_URL=http://localhost:3000 \
  -- node /absolute/path/to/mcp/server.mjs

Use

In Claude Code, just ask:

"Launch a UserDelphi study called 'Onboarding v2' on https://my-preview.vercel.app, ask testers what confused them and whether the pricing was clear."

Then later:

"Pull the UserDelphi report for that study — what's the top issue?"

Roadmap (see docs/dev-platform-plan.md)

• Scoped keys (studies:read vs studies:launch) + ud_test_ dry-run keys.
• A company budget / credits model with per-developer caps + spend holds.
• Push notifications when synthesis completes.
• GitHub/Vercel preview-deploy integration (auto-study every PR).