# MCP Configuration

This doc covers the repo-level `.mcp.json` file: what it loads, why it's checked in, and how to add or troubleshoot MCP servers.

## What MCP Is

The Model Context Protocol (MCP) is an open standard for letting LLM tools like Claude Code call external servers for additional capabilities - filesystem access, browser automation, third-party APIs, etc. An MCP server exposes a set of tools (function names, schemas, descriptions); Claude Code loads the server on startup, surfaces the tools, and invokes them on the user's behalf.

In Claude Code, MCP servers are configured at three levels: per-project (`.mcp.json` at the repo root, checked into git), per-user (global user config, outside the repo), and per-worktree (`.mcp.json` inside a worktree directory). A worktree-level `.mcp.json` overrides the repo-level one when Claude Code is launched from that worktree.

## Repo-Level `.mcp.json`

Location: `/.mcp.json` at the repo root.

Current contents:

```json
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}
```

### Why It's Checked In

`.mcp.json` is versioned because it represents the **default set of MCP servers every contributor should have loaded when working on this repo in Claude Code**. Having it in git means:

- New contributors pick up Next.js devtools access automatically on their first `claude` invocation - no manual setup step.
- The set of tools Claude has access to during repo work is reviewable and auditable.
- Changes to the tool surface are visible in PRs and get normal code review.

### What `next-devtools-mcp` Provides

`next-devtools-mcp` (published as `next-devtools-mcp` on npm) is the Next.js team's dev-tool integration for MCP-compatible clients. It exposes tools for:

- **`nextjs_docs`** - retrieving Next.js documentation relevant to the current version.
- **`nextjs_index` / `nextjs_call`** - inspecting and invoking Next.js internals during development.
- **`upgrade_nextjs_16`** - guided upgrade helpers for Next.js 16.
- **`enable_cache_components`** - experimental feature toggles.
- **`browser_eval`** - evaluating expressions in the running dev server's browser context.
- **`init`** - initialization hook.

Because the repo is on Next.js 16 (see `package.json`), this MCP keeps version-specific documentation and migration helpers one tool call away.

The `@latest` tag is intentional - it pulls the current published version on each invocation so contributors benefit from fixes without a lockstep dependency bump.

### Worktree Copies

The `setup-worktree.sh` script copies `.mcp.json` into each new worktree (observable in `.worktrees/*/.mcp.json` and `.claude/worktrees/*/.mcp.json`). These copies are byte-identical to the repo root file. If you edit `.mcp.json` at the root, existing worktrees keep their old copy - re-run setup or copy the file manually into each active worktree.

## Per-User MCPs

Contributors can - and typically do - layer additional MCP servers on top of the repo-level config via their own user-level Claude Code configuration. These are not checked into the repo and vary by person.

Common per-user additions for this codebase include ClickUp (task management), Chrome DevTools (browser automation for visual QA), probe (semantic code search), and Figma (design handoff). See `ONBOARDING.md` at the repo root for the current recommended set - that file is the source of truth for per-user tooling and is updated as the team's workflow evolves.

Per-user MCPs should **not** be moved into `.mcp.json` unless every contributor is expected to have them configured and the credentials model works for everyone (most third-party MCPs require the user to authenticate with their own credentials, which is a poor fit for a shared repo-level config).

## Adding an MCP Server to the Repo

Adding an entry to `.mcp.json` means **every contributor on this repo loads this MCP server every time they open Claude Code in this directory**. That's a meaningful expansion of what Claude can do in everyone's environment. Propose additions via PR with the following considerations addressed in the description:

### Trust

- Who publishes this MCP server? Is it a first-party tool (Next.js, Anthropic) or a third party?
- What does the server do on startup - does it make outbound network calls, read arbitrary files, or execute arbitrary code?
- If it's an npx package, is the publisher verifiable? Packages pulled via `npx -y <name>@latest` execute arbitrary code on every contributor's machine.

### Noise

- How many tools does it expose? Every tool takes up context-window real estate in Claude Code.
- Are the tools relevant to the majority of work in this repo, or niche?
- Does it pollute Claude's tool list with things that distract from the task at hand?

### Token Cost

- MCP tool schemas are loaded into context on session start. A chatty server with dozens of tools can consume thousands of tokens before the user types anything.
- Check the tool count and schema size before merging.

### Code Review Expectations

- One reviewer should verify the package exists, is maintained, and matches the claimed publisher.
- If the server requires env vars, document them in the PR and in a repo doc - do not assume contributors will know.
- Prefer pinning a version (`@1.2.3`) over `@latest` when the server is not first-party and stability matters more than staying current.

## Troubleshooting

### "MCP tool not available in Claude"

Work through these in order:

1. **Confirm you launched Claude Code from the directory containing `.mcp.json`.** Claude Code reads `.mcp.json` from the current working directory on launch. Running from a parent directory or a worktree without a copy of the file will not load the repo-level MCP.
2. **Check that `npx` can install the package.** Run `npx -y next-devtools-mcp@latest --help` (or equivalent) manually. Stale npx cache (`~/.npm/_npx/`) occasionally keeps a broken version pinned - clear it with `rm -rf ~/.npm/_npx` and retry.
3. **Confirm the MCP server actually started.** Claude Code logs MCP server startup failures. Check the Claude Code logs for load errors - missing dependencies, failed installs, or crashed servers all show up there.
4. **Check your user-level Claude config isn't overriding `.mcp.json`.** A per-user entry with the same server name as the repo-level one wins. Remove or rename the conflicting user-level entry.
5. **Verify the tool name you expect.** MCP tool names are namespaced (e.g., `mcp__next-devtools__nextjs_docs`). The tool you're looking for may exist under a different name than documented elsewhere.
6. **Restart Claude Code.** MCP servers are loaded on session start. Config changes are not picked up until the next `claude` invocation.

### "MCP server crashes on load"

Look at the Claude Code logs for the server's stderr output. Common causes:

- Node version mismatch between the MCP package's requirements and the system Node.
- Missing system dependency (e.g., Chrome not installed for a browser-automation MCP).
- Network issue reaching the npm registry on first install.

### "Different MCPs load in different worktrees"

This is expected - each worktree has its own `.mcp.json` copy that was taken at the time `setup-worktree.sh` ran. Sync them by copying the current root `.mcp.json` into the worktree or re-running the setup script.

## Related: The App's Inbound MCP Server

This doc covers the **client-side** MCP config (`.mcp.json`) that Claude Code sessions working on this repo consume.

The app **also** exposes its own inbound MCP server at `mcp/dealer-lookup/` - used by admins via Claude Code for customer support (read-only dealer/user/Stripe lookups). That is a separate concern documented in [`MCP_SERVER.md`](./MCP_SERVER.md).

- **This doc (`MCP_CONFIGURATION.md`):** what MCP servers _we consume as clients_ when working on the repo.
- **[`MCP_SERVER.md`](./MCP_SERVER.md):** what MCP server _we expose_ to authenticated clients.