Monorepo Workflows with AI Assistants

A security advisory drops for your auth library. It lives in @company/core, and 23 services across a 47-package monorepo import it. You need to know exactly which packages break, in what order they rebuild, and which teams to ping. Open the wrong file first and you spend the afternoon chasing transitive imports that a project graph could have answered in seconds.

Out of the box, AI assistants treat your monorepo as a pile of files. They have no idea that web-app depends on @company/ui, which depends on @company/core. The fix is a project-graph MCP server (Nx Console is the most mature) that hands the model your dependency graph, generator schemas, and task cache as structured context. Once that’s wired up, “what breaks if I change this?” becomes a query, not a manual audit.

What You’ll Walk Away With

• A working Nx MCP setup in Cursor, Claude Code, and Codex so the model can read your project graph
• A reusable impact-analysis prompt that returns affected packages in dependency order before you touch code
• A build-optimization prompt that turns nx.json/turbo.json task graphs into concrete parallelization wins
• A cross-package refactor workflow that keeps imports and types consistent across dozens of packages
• Recovery steps for the failure modes you will actually hit: stale graphs, uvx missing, the MCP server failing to start

Setting Up Project-Graph MCP Servers

The Nx MCP server (nx-mcp) is the most capable monorepo integration today. It exposes your project graph, generator schemas, and Nx docs as tools the model can call. Setup is nearly identical across all three tools — the only real difference is the command you run.

Caution

Recent nx-mcp runs in “minimal” mode by default, which hides the workspace-analysis tools the prompts below rely on — including nx_workspace, nx_project_details, nx_generators, and nx_generator_schema — because Nx now ships that functionality as agent skills instead. If your agent uses those skills, the default is fine. If you want the model to call the graph tools directly (as the impact-analysis and refactor prompts here assume), add --no-minimal to the command — for example npx -y nx-mcp --no-minimal.

Cursor

Install the Nx Console extension. In an Nx workspace, Cursor (0.46+) auto-detects it and shows a notification offering to enable the Nx MCP server. Accept it, and Nx Console writes a .cursor/mcp.json entry for you.

To wire it up manually, run nx.configureMcpServer from the command palette (Cmd/Ctrl+Shift+P), or add the entry yourself:

.cursor/mcp.json

{
  "mcpServers": {
    "nx": { "command": "npx", "args": ["-y", "nx-mcp"] }
  }
}

Confirm it under Cursor Settings → MCP — you should see nx listed with a green dot.

Claude Code

Add it as a stdio server from the repo root. Use --scope project so the config is written to a shared .mcp.json rather than the default local scope (which lives in ~/.claude.json under your project path and is private to you). The --scope flag must come before the server name and the --:

claude mcp add nx --scope project -- npx -y nx-mcp

Verify it registered and is reachable:

claude mcp list

With --scope project, the config lands in .mcp.json. Commit that file so the whole team gets the same graph-aware setup.

Codex

Register the same stdio server. Codex stores it in ~/.codex/config.toml:

codex mcp add nx -- npx -y nx-mcp
codex mcp list

For larger workspaces, give the server more startup headroom in ~/.codex/config.toml:

[mcp_servers.nx]
command = "npx"
args = ["-y", "nx-mcp"]
startup_timeout_sec = 30

Note

Turborepo and Bazel users: There is no official Turborepo MCP server yet — it is still an open Vercel discussion (turborepo#10130), not a release. In the meantime, install Nx Console anyway: its project-graph tools work against any workspace once you point them at your packages, and you can pair it with a git server for change coordination. For Bazel, lean on a filesystem server plus bazel query output pasted into context.

Adding Git and Filesystem Context

Two more servers round out a monorepo setup. Note the launchers differ: the official filesystem server is a Node package run via npx, while the git server is Python-only and runs via uvx (install uv first). There is no @modelcontextprotocol/server-git on npm — that package does not exist.

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/monorepo"]
    },
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/monorepo"]
    }
  }
}

Claude Code

claude mcp add git -- uvx mcp-server-git --repository /path/to/monorepo
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/monorepo

Codex

codex mcp add git -- uvx mcp-server-git --repository /path/to/monorepo
codex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path/to/monorepo

Scoping the filesystem server to the monorepo root keeps bulk operations inside your workspace and out of the rest of your disk.

Impact Analysis Before You Touch Code

The single highest-value monorepo move is asking the model what breaks before editing. With the Nx MCP active, the model calls nx_workspace and nx_project_details instead of guessing from import statements.

Tip

Copy-paste prompt for change-impact analysis:

Using the Nx project graph, I’m adding an optional status: 'active' | 'suspended' field to the User interface exported from @company/core. Tell me:

1. Every package that imports User (direct and transitive), in rebuild order.
2. Which of those will break at compile time vs. which are safe because the field is optional.
3. The specific components that render user data and should surface the new field. Output a checklist grouped by package. Do not edit anything yet — I want the plan first.

With real graph context, you get back something you can act on rather than a guess:

User is imported by 8 packages. Adding status as optional is non-breaking at the type level. The packages that render user data and should be updated to show status: UserCard (web-app), UserProfile (mobile-app), UserList (admin-dashboard). Rebuild order: @company/core → @company/ui → web-app, mobile-app, admin-dashboard.

That checklist is the difference between a controlled change and an afternoon of grep. The model read your actual graph, so the rebuild order and the “optional means non-breaking” call are grounded, not invented.

Cross-Package Refactoring

Once you trust impact analysis, the same graph awareness drives coordinated edits. The workflow is the same across all three tools — the model proposes the plan, you approve it, then it executes package by package — so the difference is only in how you drive each tool. Cursor’s agent mode applies edits inline with checkpoints; Claude Code runs in the terminal and can chain into hooks or CI; Codex can fan the work out to background worktrees or the cloud.

1. Get the plan first. Run the impact prompt above so you have the affected-package checklist in dependency order.

2. Refactor in graph order. Ask the model to work bottom-up so each package compiles before its dependents change:

   Tip

   Copy-paste prompt for a coordinated rename:

   We’re renaming getUser(id) to fetchUserById(id) across the monorepo. Using the Nx graph, refactor in dependency order: update the definition in @company/core first, then every consumer. For each package, change call sites, update mocks in test files, and keep TypeScript types in sync. Add a deprecated getUser alias that re-exports fetchUserById so nothing breaks mid-migration. Show me the diff per package and stop before committing.

3. Verify with the build graph. Run only what changed — npx nx affected -t build test lint — and feed any failures back to the model with the package name and error.

Caution

Resist one giant “refactor everything” prompt. Large monorepo edits drift: the model loses track of which package it’s in and starts inventing exports. Keep each turn scoped to one package or one slice of the graph, verify with nx affected, then move on. The deprecated-alias trick keeps the tree green between steps.

Build Optimization

Slow CI is usually a task-graph problem, not a hardware problem. The Nx MCP lets the model read your actual nx.json and project configs instead of giving generic advice.

Tip

Copy-paste prompt for build optimization:

Read our nx.json and project configurations through the Nx MCP. Our CI build step takes ~9 minutes. Identify:

1. Tasks declared as dependencies that aren’t real (e.g. apps depending on each other’s build output unnecessarily).
2. Cache misses caused by overly broad inputs globs.
3. Targets that could run with parallel but currently don’t. For each finding, give me the exact config change and an estimated time saved. Cite the file and line.

A graph-aware model gives you specifics you can paste into a PR:

Your web-app:build declares a dependency on mobile-app:build, but nothing in web-app imports mobile-app. Removing that edge lets the two apps build in parallel — roughly 40% off the critical path. Separately, your test target’s inputs include **/*.md, so doc edits bust the test cache. Narrow it to ["default", "^default"].

For Turborepo, the same pattern applies to turbo.json — ask the model to audit inputs, outputs, and dependsOn — but you’ll feed it the file contents directly rather than through an MCP tool until an official server ships.

Release Coordination

Multi-package releases are where dependency order bites hardest: ship @company/payments before the @company/core it depends on and you publish a broken version. Pair the git MCP (commit history) with the Nx MCP (dependency order) for this.

Tip

Copy-paste prompt for release planning:

Using the git MCP for commit history and the Nx graph for dependencies, plan the next release. Since the last tag:

1. Group commits by affected package.
2. Classify each as patch, minor, or major using Conventional Commits.
3. Flag any breaking change that forces a major bump in a dependent package too.
4. Produce a publish order that respects the dependency graph.
5. Draft changelog entries per package, linking the relevant commits. Output a release table: package, current version, proposed version, publish order.

When This Breaks

Graph-aware tooling fails in a handful of predictable ways. Recognize them fast:

• The MCP server doesn’t start. Run claude mcp list (or codex mcp list) — a server stuck in “failed” usually means the launcher binary is missing. For nx-mcp and the filesystem server you need Node/npx on PATH; for the git server you need uv/uvx. Install uv if uvx is “command not found”.
• You used @modelcontextprotocol/server-git and got a 404. That package isn’t on npm — the git server is Python-only. Use uvx mcp-server-git --repository /path instead.
• The model can’t find your projects. Nx MCP needs to run from (or be pointed at) the workspace root where nx.json lives. If the model says “no Nx workspace detected”, restart it from the repo root.
• Impact analysis is stale. The project graph is cached. After adding or moving packages, run npx nx reset to clear the Nx cache, then ask the model to re-read the graph before trusting a new impact report.
• Large prompts time out or hallucinate exports. On big workspaces, the graph payload can blow past the context window. Narrow the request to one package or one slice (nx affected --base=main), and bump startup_timeout_sec for the server if it’s timing out on first call.

Codex Background Worktrees for Long Migrations

Monorepo migrations are slow and parallelizable, which makes them a fit for Codex’s multi-surface model. Codex runs background tasks in dedicated git worktrees so a long refactor doesn’t tie up your working tree. Kick off a cloud task per package group, then pull the results locally:

# Browse or run cloud tasks from the terminal
codex cloud

# Apply a completed cloud task's diff to your local tree
codex apply

This lets you fan a “migrate package group A to the new API” task out to the cloud while you keep editing locally, then review each diff with codex apply before it lands.

What’s Next

Large Codebases

Context strategies for repos too big to fit in a window — the prerequisite skill for any monorepo. See Working with Large Codebases.

Microservices

Coordinate changes across service boundaries with the same graph-first mindset. See Microservices Workflows.

Code Quality at Scale

Keep linting, types, and tests consistent across every package. See Code Quality Workflows.

MCP Ecosystem

Go deeper on configuring and combining MCP servers across all three tools. See the MCP Ecosystem guides.