MCP Integration

Rex and SourceVision expose Model Context Protocol servers for AI tool integration. This lets Claude Code, Codex, or any MCP client query your codebase and manage your PRD directly.

Setup by Assistant

Claude Code

ndx init writes a tracked .mcp.json at the project root (cwd-relative commands, e.g. {"command":"ndx","args":["rex","mcp","."]}) and read-only tool permissions to .claude/settings.local.json. .mcp.json is committed to the repo, so every worktree and teammate clone gets a working registration without any claude mcp add call — MCP works out of the box after init. Claude Code shows a one-time approval prompt for a project's servers the first time it opens the checkout.

If ndx isn't on PATH, run the CLI through npx instead: npx -y @n-dx/core rex mcp . / npx -y @n-dx/core sv mcp .. Pass --mcp-scope=local to ndx init to fall back to the older claude mcp add --scope local registration (per-machine, absolute server path) instead of .mcp.json. The project directory it records is cwd-relative, like .mcp.json's — an absolute one would pin every worktree of the repository to a single checkout, because Claude Code applies a repository's local-scope entry to sessions started in its linked worktrees. ndx init reports any absolute-path entry it finds along with the claude mcp remove --scope local command that retires it.

Worktree sessions

Claude desktop starts a worktree session's project servers in the main checkout (so . resolves there) while the session itself runs in <repo>/.claude/worktrees/<name>. The stdio rex and sourcevision servers, and ndx mcp <server> when it bridges to the hub, resolve their workspace from the client's MCP roots (roots/list) and rebind on roots/list_changed, so writes land in the session's own PRD. Clients that advertise no roots keep the launch directory. A root outside the repository, or one that can't be served, refuses writes with an error rather than misrouting them.

Verify a session's write target with rex get_capabilities — its workspace block reports source (roots when the client's root was used, startup for the launch directory), projectDir (the tree being written), and refused (set while writes are refused). In a desktop worktree session source should read roots.

For multi-project setups, HTTP transport goes through the per-user hub, which gives each project its own endpoint — see Transport Options below.

Codex

ndx init writes MCP server definitions to .codex/config.toml using stdio transport. Codex reads this file automatically — no manual registration required.

The generated config looks like:

[mcp_servers.rex]
command = "node"
args = ["node_modules/@n-dx/rex/dist/cli/index.js", "mcp", "."]

[mcp_servers.sourcevision]
command = "node"
args = ["node_modules/@n-dx/sourcevision/dist/cli/index.js", "mcp", "."]

Transport Options

stdio (default)

stdio spawns a separate process per MCP server. No ndx start required. Both Claude and Codex support stdio transport, and ndx init registers it automatically for both:

• Claude Code: tracked .mcp.json (see Setup by Assistant above) — no manual claude mcp add needed.
• Codex: automatic via .codex/config.toml, generated by ndx init.

HTTP — through the hub

ndx start . registers the repository with the per-user hub and serves it at http://localhost:3117/p/<id>/. Each project's MCP endpoints are …/p/<id>/mcp/rex and …/p/<id>/mcp/sourcevision, so several projects share the port without collision. Register them with your assistant:

# 1. Start the server (dashboard + MCP on one port)
ndx start .

# 2. Read the project id from the URL it prints (or run `ndx hub status`)

# 3. Register HTTP MCP servers (Claude example)
claude mcp add --transport http rex http://localhost:3117/p/<id>/mcp/rex \
  --header "X-Ndx-Token: $(cat ~/.ndx/auth.token)"
claude mcp add --transport http sourcevision http://localhost:3117/p/<id>/mcp/sourcevision \
  --header "X-Ndx-Token: $(cat ~/.ndx/auth.token)"

Any MCP-compatible assistant can connect to these HTTP endpoints.

The server runs on port 3117 by default. Custom port: --port=N or ndx config web.port N .

HTTP transport uses Streamable HTTP with session management. Sessions are created automatically and identified by the Mcp-Session-Id header; the hub proxies, and each project's own server owns its sessions.

Benefits of HTTP: single process, shared port with dashboard, session management, no per-tool process overhead.

Bare aliases. While exactly one project is registered, http://localhost:3117/mcp/rex and /mcp/sourcevision still alias to it. With several projects registered, root MCP calls answer 409 listing the ids, so register the /p/<id>/ form.

Per-user token. ndx start creates <ndx home>/auth.token (mode 0600), normally ~/.ndx/auth.token. Every hub, dashboard and preview request must present it as an X-Ndx-Token header, an Authorization: Bearer header, or the ndx_token cookie that the printed URL sets once. Without it a request is refused with 401. Disable the check with ndx start --no-auth or web.auth: false in .n-dx.json; the --header flags above are then unnecessary.

Tool Name Prefixes

MCP tool names differ by assistant due to vendor-specific conventions:

Tool	Claude Code	Codex
PRD status	mcp__rex__get_prd_status	get_prd_status
Next task	mcp__rex__get_next_task	get_next_task
File info	mcp__sourcevision__get_file_info	get_file_info

Claude uses double-underscore prefixes (mcp__{server}__{tool}) to namespace tools. Codex uses bare tool names. Both invoke the same underlying MCP server — the prefix is a transport-layer convention, not a functional difference.

Rex MCP Tools

Rex reads the PRD's layout from disk. A v2 PRD is the product layer (.ndx/rex/product/) plus the change layer (.ndx/rex/changes/); see The PRD. ndx init creates v2 projects. A v1 project, one that has not yet run ndx migrate, keeps .rex/prd_tree/ (one tree of items with levels), and the product-layer tools refuse it.

Product layer and changes

Tool	Description
get_product	The product layer. By default each area with its counts by computed status, defective nodes and open changes; area returns one area's capabilities and constraints with status and health; full: true returns every area that way. v2 only
get_capability	One capability or constraint: statement, capability criteria, parent chain, status, health, and the changes that amend or touch it. v2 only
place_change	Without a target, the shortlist of capabilities and constraints a change could amend or touch; with one, record it (touches or amends; an applied change takes touches only, since its amendments already reached the map); with propose (type, under, title) instead, record a new capability or constraint when nothing fits. v2 only
apply_change	Apply a change's amendments to the product layer, as a steward. Refused whole, listing every problem, when an amendment does not fit. v2 only

Work items

Tool	Description
get_prd_status	PRD overview. v2: change counts, the Inbox count, product status per area and change counts per release. v1: the item tree with completion stats
get_next_task	Next actionable task (skips tasks another worktree has claimed)
claim_task	Hold a task for this worktree
release_task	Give back a claim
add_item	Add an item. v2: pass type (change, the default, lands in the Inbox; task or subtask with parentId), and optionally amends or touches. v1: pass level. acceptanceCriteria is the item's "done when". Optional run block of saved run settings: portable tier plus optional per-vendor models pins
update_task_status	Update item status
edit_item	Edit item content (title, description, priority, tags, run). A run object replaces the whole saved block; null removes it
get_item	Full item details with parent chain; on v2, any node by id, display id or alias
move_item	Reparent an item
merge_items	Consolidate duplicate items
verify_criteria	Map acceptance criteria to tests
reorganize	Detect and fix structural issues
health	PRD structure health score
facets	List configured facets
get_recommendations	SourceVision-based recommendations
append_log	Write to the execution log
get_token_usage	Hench run token totals per PRD item, with orphans surfaced separately
get_capabilities	Server capabilities and configuration, plus the workspace block (resolved project dir, source, refusal)

get_capabilities describes the MCP server; get_capability reads one capability of the product layer.

SourceVision MCP Tools

Tool	Description
get_overview	Project summary statistics
get_file_info	File inventory, zone, and imports
search_files	Search inventory by path, role, or language
get_zone	Architectural zone details
get_findings	Analysis findings (anti-patterns, suggestions)
get_next_steps	Prioritized improvement recommendations
get_imports	Import graph edges
get_classifications	File archetype classifications
get_route_tree	Route structure (pages, API routes, layouts)
get_readiness	SDLC readiness scorecard: whether each practice exists and is wired up, not how good it is
set_file_archetype	Override archetype classification for a file

Migrating from stdio to HTTP (Claude)

# 1. Register the repository with the hub; read the project id from the
#    URL it prints (or `ndx hub status`)
ndx start --background .

# 2. Remove old stdio servers
claude mcp remove rex
claude mcp remove sourcevision

# 3. Add HTTP servers
claude mcp add --transport http rex http://localhost:3117/p/<id>/mcp/rex \
  --header "X-Ndx-Token: $(cat ~/.ndx/auth.token)"
claude mcp add --transport http sourcevision http://localhost:3117/p/<id>/mcp/sourcevision \
  --header "X-Ndx-Token: $(cat ~/.ndx/auth.token)"

---

See the Skills Reference for the workflow slash commands installed alongside MCP by ndx init.