Wire NCI into Claude

Claude Desktop

The GUI app loads MCP servers from a single JSON file at launch.

Locate the config

If the file doesn’t exist, create it. On macOS you can shortcut to it via SettingsDeveloperEdit Config.

Drop in the entry

{
  "mcpServers": {
    "nci": {
      "command": "npx",
      "args": ["-y", "@nativecontextindex/mcp"]
    }
  }
}

That is the whole entry. nci-mcp resolves its working directory from the launcher and reads nci.config.json the same way the CLI does — there is no NCI_PROJECT_ROOT env var.

When you need NCI_BINARY

If nci isn’t on the launcher’s PATH (common on macOS GUI apps), point at the binary explicitly:

{
  "mcpServers": {
    "nci": {
      "command": "npx",
      "args": ["-y", "@nativecontextindex/mcp"],
      "env": {
        "NCI_BINARY": "/absolute/path/to/nci"
      }
    }
  }
}

Find the absolute path with:

Reload Claude Desktop

Quit fully — ⌘Q on macOS, or right-click the system tray icon and choose Quit on Windows — then relaunch. The config is read only at startup and changes are not hot-reloaded; closing the window or starting a new conversation is not enough. After relaunch, open the connected tools panel — nci should appear with two tools (nci_query, nci_sql) and three resources (nci://primer/agent, nci://primer/reference, nci://database/active).

Claude Code

The CLI uses a claude mcp subcommand to register servers; you don’t hand-edit JSON.

Add the server

The -- (double dash) separates Claude’s flags from the command Claude Code spawns for the server. --scope user stores it under ~/.claude.json so it’s available across every repo.

If you want the server scoped to one repo (and checked into version control for teammates), use --scope project — Claude writes the entry to .mcp.json in the repo root:

When you need NCI_BINARY

Pass it through with --env:

(All flags must appear before the server name; the command after -- is what Claude spawns.)

Verify

The first shows every registered server; the second prints the resolved command, args, env, and scope for nci. Restart your Claude Code session after adding so the tool catalog refreshes.

First call (both clients)

The agent should read nci://primer/agent first — that resource is the operating manual the MCP server’s instructions field points it to. Then ask something like:

What overloads of useState does my installed React expose?

Claude routes to nci_query with subcommand: "evidence" (or overloads once it has an id) and quotes the signature back verbatim.

Troubleshooting

The server speaks JSON-RPC over stdio with no startup banner — it sits silent waiting for a tools/list from the client. If Claude says “tool unavailable”:

• nci is not on PATH and NCI_BINARY is unset. Set it.
• The repo hasn’t been indexed yet. Run nci index.
• Two MCP entries conflict on the name nci. Rename one (e.g. nci-monorepo).
• Claude Code only: claude mcp list shows the entry but a tools/list is empty — the binary couldn’t spawn. Run claude mcp get nci to inspect the resolved command, then try the command directly in a shell.

Skills

Claude follows the open Agent Skills standard. NCI’s shipped skill (nci-answer-quality) drops into Claude’s discovery path with no rewriting — see NCI Skills for the host-by-host map.