MCP, overlay, and the browser extension
Connect your IDE via MCP and the Crux Chrome extension so code and live UI cite experience short IDs.
Settings covers Setup MCP, External sources → AI assistants / Build, and the Browser Extension. Use Create → Experience scan in Experience to connect a site URL and import pages.
Setup MCP
- Open Settings → External sources:
- AI assistants for Claude, ChatGPT, Grok, and other clients used to capture research.
- Build for Cursor (one-click), Codex, Windsurf, and VS Code.
- Or use Settings → Setup MCP for the full client list.
- Install with the button or one-command copy for your client.
- Connect in your client. New grants include write by default so clients can capture research, create experience entities, register code tags, and schedule work. Opt out in Settings → Integrations if needed.
- Capture research from the conversation (
capture_researchfor notes / questions / assumptions;capture_research_artefactfor personas, journeys, tables, flow shells), ask about the experience (ask_why/get_experience_story), plan the work (list_plan,upsert_activity,create_todo), build the whole product (scaffold_experience), or implement a specific element — your agent should callregister_code_referenceand applycrux-attr="ex-…"automatically. Missing experience entities are created in Crux for you. - In the Experience list, each entity's sync status shows whether it has actively tracked code — Synced, Stale, or Not synced.
Captured research carries an MCP provenance chip (with optional client name such as Claude Desktop or Cursor) so you can enrich and label it later in Crux.
Read and write
Every client — assistant or IDE — connects to the same endpoint and the same tools. What separates them is the client's own capabilities, not Crux's: Claude, ChatGPT, and Grok can read your graphs and write to them exactly as Cursor can.
Read works as soon as you sign in:
| Tool | Reads |
|---|---|
list_projects, get_project | Your projects and their settings |
list_plan, list_todos | Scheduled activities and to-dos, plus anything undated |
list_experience_entities, get_experience_story | Pages, features, content — and why each exists |
list_code_references, list_figma_links | Code and design links behind an entity |
ask_why | An answer across research and experience, with citations |
list_usability_findings, search_usability_heuristics | Usability findings and the cited benchmark |
list_briefs, get_brief, list_canvas_nodes, get_canvas_node | Briefs and canvas content |
Write needs the connection's crux:write:project permission, which is on by default:
| Tool | Writes |
|---|---|
capture_research, capture_research_artefact | Notes, questions, assumptions, evidence, personas, journeys, tables |
upsert_activity, create_todo | Activities and to-dos with dates, owners, and links between them |
scaffold_experience, create_experience_entity | Pages, features, content, menus, sitemaps |
register_code_reference, sync_code_references | Code references and crux-attr short IDs |
run_usability_scan | A usability scan whose findings land in Research |
If write is off, those tools return a message telling the agent to ask you to turn it on. Toggle it per connection in Settings → Integrations — turning it off is remembered, so it won't be re-enabled by a later update.
Plan the work from your assistant
Ask any connected assistant to plan, schedule, or sequence work and it reads the current plan with list_plan, proposes activities and to-dos in the chat, and only writes them once you have agreed the shape — upsert_activity for each activity, then create_todo for the work beneath it. Because activities are matched on title, running a revised plan updates it rather than duplicating it.
Everything it schedules appears on the Crux Plan calendar and timeline; undated items wait in the unscheduled tray until you drag them onto a day. Assistants write activities and to-dos; milestones — the outcome level above them — are set in Crux itself, or drafted by the Crux Agent with Break down a goal. See Plan: calendar & timeline.
Per-client setup guides:
View Experience on the live site
To inspect an entity in context on production (or staging):
- In Experience → Create → Experience scan, set the project site URL and scan — or scan from the extension after linking a project.
- In Settings → Browser Extension, install from Chrome, then Sign in to Crux in the extension and Link a project.
- Ensure the live site ships
crux-attr="ex-…"on the matching DOM roots (via MCP tagging). - Open an entity and click View on site. Crux opens
{siteUrl}{pagePath}?crux=ex-######. - The page scrolls to that element, highlights it, and opens the why-story panel.
If View on site is disabled, connect a site URL first. If nothing highlights, the live DOM is missing that crux-attr — re-tag from your IDE and deploy.
Browser Extension
Beyond deep links, the extension's side panel works on any page of a linked site: ask a research question about the current page and add the answer to Crux, run an Experience scan on the live tab, and click green badges on tagged elements for their why-story.
The Usability tab scans the tab you are on against the usability benchmark and pins each finding onto the page, coloured by severity. Because it reads the live DOM rather than fetched HTML, it also covers the accessibility and performance checkpoints a server-side scan has to skip — see Usability scan.
See also
Related articles
Documents: MCP & browser extension