How do I install UserProof in Codex or Cursor?
In Codex, run codex mcp add userproof -- npx -y github:GetUserProof/userproof and raise the start timeout to 60 seconds. In Cursor, add an entry named userproof to ~/.cursor/mcp.json. Restart the agent, then ask it to set up UserProof: it signs you in, adds the script tag and proves it records. Free covers 3 sites.
We ran these steps on November 7, 2026. The server started on a clean machine in 4.2 seconds and listed 14 tools, the output is below. Both agents run the same server; only the config file differs.
Jump to: quick picks · Codex · Cursor · run setup · what we saw · if it stops · FAQ
Quick picks: which agent are you in?
| You use | Do this |
|---|---|
| Codex CLI or the Codex IDE extension | One command, then one line in config.toml. |
| Cursor | One entry in the Cursor mcp.json file. |
| Claude Code | Use the plugin instead: How do I set up UserProof in Claude Code? |
| Windsurf or another MCP agent | Add an MCP stdio server named userproof that runs npx -y github:GetUserProof/userproof. |
Install UserProof in Codex
- Add the server. In any terminal:
Done looks likecodex mcp add userproof -- npx -y github:GetUserProof/userproofAdded global MCP server 'userproof'. - Give it time to start. Open
~/.codex/config.tomland add one line under the new section, so it reads:
Codex's default is 10 seconds, and the first start downloads the server. Done looks like[mcp_servers.userproof] command = "npx" args = ["-y", "github:GetUserProof/userproof"] startup_timeout_sec = 60codex mcp listshowinguserproofasenabled. - Restart Codex. Done looks like
userproofin the list when you type/mcpin the Codex terminal UI.
To write the entry for another agent too, use the MCP config generator. Using the ChatGPT desktop app? It reads the same Codex config: see how to connect ChatGPT to UserProof.
Install UserProof in Cursor
- Open the config file.
~/.cursor/mcp.jsonin your home folder works for every project;.cursor/mcp.jsoninside a project works for that project only. Create it if it is missing. - Add the entry under
mcpServers, keeping any servers already there:
Done looks like a file that still parses as JSON (a missing comma is the usual mistake).{ "mcpServers": { "userproof": { "type": "stdio", "command": "npx", "args": ["-y", "github:GetUserProof/userproof"] } } } - Restart Cursor or reload its MCP servers. Done looks like
userprooflisted with its tools in Cursor's MCP settings.
Run setup from the agent
The tools need an account and a site before they return anything, and setup makes both. Open your site's project folder in the agent and ask it to follow https://getuserproof.com/setup.md. It asks about your site's goal once, gives you a sign-in link to open in your own browser, adds the script tag to your layout, then opens your dev server and waits for the first event. The script tag itself is explained on what the script tag records.
Done looks like the agent reporting status received. After you deploy and real visitors arrive, ask "what should I work on?" to get one fix with the file and line, for example a dead click or rage click on your sign-up button.
What we saw when we ran it
On November 7, 2026 we added the server to a fresh Codex config with Codex CLI 0.167.0, then started the server on its own over stdio and sent it the two messages any MCP client sends first, initialize and tools/list. No account or key was used.
$ codex mcp list
Name Command Args Status
userproof npx -y github:GetUserProof/userproof enabled
initialize after 4.2 s: {"name": "userproof", "version": "3.10.0"} 2025-06-18
14 tools: list_sites, select_site, get_top_fix, fleet, mark_fix_applied,
set_industry, set_goal, upgrade, check_fix, wait_for_first_event,
scan_site, check_coverage, get_activation, get_usage
A second start, with the download cached, answered in 3.8 seconds. Both fit inside a 60-second timeout. The first download took less than half of Codex's 10-second default, so a slower connection could pass it. We did not run Cursor itself in this test; its entry runs the same command shown above.
If it stops
- Codex says the server timed out. The
startup_timeout_sec = 60line is missing or sits under a different section. - Cursor shows no tools. Check that the file is valid JSON and that
npxworks in a terminal (it needs Node.js). - The tools answer "run setup". The server has no key yet. Run setup; sign-in writes the key to
~/.config/userproof/key, so it never goes in a config file. - The tools are still missing after setup. Restart the agent so it reconnects to the server.
Still choosing a tool before you install one? Our ranking of website analytics for AI coding agents compares 7, with how each connects to an agent.
What it costs
Installing and setup are free. Free covers 3 sites and 5,000 recorded visits a month; Pro is $29 a month for 50,000 and Scale is $99 a month for 250,000. Read from our pricing page on November 7, 2026. The 14 tools the agent gets are listed on the session replay MCP server page, and upgrading to Pro is one request to the agent.
After setup, you can keep part of your site out of recordings.
FAQ
Why does Codex say the UserProof server timed out?
Codex waits 10 seconds for an MCP server to start by default. The first start downloads the server from GitHub, so set startup_timeout_sec = 60 under [mcp_servers.userproof] in ~/.codex/config.toml. In our test on November 7, 2026, the server answered after 4.2 seconds on a clean machine.
Do I add UserProof to Cursor per project or for every project?
Either works. ~/.cursor/mcp.json in your home folder makes it available in every project; .cursor/mcp.json inside one project keeps it there. The API key is not in either file: the server reads it from ~/.config/userproof/key, which sign-in writes.
Does the same setup work in the Codex IDE extension?
Yes. The Codex CLI and the IDE extension read the same ~/.codex/config.toml, so a server added with codex mcp add shows up in both. In the extension you can also add it from the gear menu under MCP servers.
Can I use UserProof in Windsurf or another agent?
Any agent that runs stdio MCP servers can use it: add a server named userproof that runs npx -y github:GetUserProof/userproof. Then run the same setup steps as in Codex or Cursor.
Sources, read November 7, 2026
- UserProof setup steps for each agent: setup.md, read November 7, 2026
- OpenAI, OpenAI MCP docs for Codex (codex mcp add, startup_timeout_sec default 10, the IDE extension), read November 7, 2026
- Cursor, MCP docs (global and project mcp.json), read November 7, 2026
- Our test: Codex CLI 0.167.0 and the UserProof MCP server 3.10.0 from the GetUserProof/userproof repository, run November 7, 2026
- UserProof plans: pricing page, read November 7, 2026