# Connect your AI assistant to Niro

`niro mcp install` configures one AI client at a time to use Niro's MCP server. This page
lists every supported client, the exact command for each, and what it does. If you'd rather
drive setup from chat instead of a terminal, see [Scenario 2](../README.md#scenario-2--onboard-a-folder-youre-working-in)
in the main README — the `niro-cli` skill can run these commands for you.

## Before you start

```bash
npm install -g @niroai/niro
niro login              # browser device flow — no API key to copy
```

After `niro login`, none of the commands below need an API key — the MCP server authenticates
with your device token. If you'd rather use an API key instead (e.g. a headless CI box), get
one from **console.niroai.dev > Settings > Account**; the wizard will ask for it when no
`niro login` session is found.

**Pointing at a different backend?** Every command below defaults to Niro's cloud
(`https://aiassistant.niroai.dev`). Add `--url <your-backend-url>` to any `niro mcp install`
command to use a self-hosted or dedicated instance instead (or set `NIRO_MCP_SERVER_URL`).

## All Niro tools are read-only

Every tool Niro exposes over MCP only *reads* your code graph — none can modify your code,
your projects, or anything else. That's why several of the installers below turn on
auto-approve for Niro's tools: there's nothing for a read-only tool call to break.

---

## Claude Code

```bash
niro mcp install --client claude-code
```

Registers the server (`claude mcp add --scope user`), adds a `PostCompact` + `UserPromptSubmit`
hook so Claude stays aware of Niro after context compaction, appends a short reminder to
`~/.claude/CLAUDE.md`, and installs the **`niro-skill`** (routes code questions through the
graph) and **`niro-cli`** skill (drives the CLI from chat) to `~/.claude/skills/`.

Verify: type `/mcp` inside Claude Code — `niro` should be listed as connected.

## Codex

```bash
niro mcp install --client codex
```

Registers the server in `~/.codex/config.toml`, sets `default_tools_approval_mode = "auto"`
(safe — every niro tool is read-only), appends a reminder to `~/.codex/AGENTS.md`, and installs
the shared `niro-skill` + `niro-cli` skill to `~/.agents/skills/` (also read by Windsurf).

Verify: `/mcp` inside the Codex TUI.

Note that `AGENTS.md` is read once at the start of a session, so on a long task the reminder to
prefer niro's tools carries less weight than it does in Claude Code, where a per-tool-call hook
reinforces it. A per-prompt hook for Codex is in progress.

## Cursor

```bash
niro mcp install --client cursor
```

Writes `~/.cursor/mcp.json`, adds `"niro:*"` to `~/.cursor/permissions.json`'s `mcpAllowlist`
(so Agent doesn't ask before every tool call), and writes a project rule to
`.cursor/rules/niro.mdc` in the current repo.

Requires Cursor's Agent **Auto-run** mode enabled (Settings) for the allowlist to take effect —
"Ask every time" ignores it.

## VS Code (GitHub Copilot)

```bash
niro mcp install --client vscode
```

Writes the user-profile `mcp.json` (`servers.niro`) — the same file VS Code's
**MCP: Open User Configuration** command opens.

Verify: run **MCP: List Servers** from the Command Palette, or check the Chat view's tools icon.
First use of a new server needs a one-time trust confirmation.

## Windsurf

```bash
niro mcp install --client windsurf
```

Writes `~/.codeium/windsurf/mcp_config.json`, appends a reminder to
`~/.codeium/windsurf/memories/global_rules.md`, and installs the shared `niro-skill` +
`niro-cli` skill to `~/.agents/skills/` (also read by Codex).

## Claude Desktop

```bash
niro mcp install --client claude-desktop
```

Writes `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
`%APPDATA%\Claude\`, Linux: `~/.config/claude/`). Restart Claude Desktop after.

## Gemini CLI

```bash
niro mcp install --client gemini-cli
```

Runs `gemini mcp add -s user` to register the server (`~/.gemini/settings.json`) and appends a
reminder to `~/.gemini/GEMINI.md`.

Verify / reload: run `/mcp reload` inside Gemini CLI.

## GitHub Copilot CLI

```bash
niro mcp install --client copilot-cli
```

Runs `copilot mcp add` (writes `~/.copilot/mcp-config.json`) and appends a reminder to
`~/.copilot/copilot-instructions.md`.

Verify: run `/mcp` inside the Copilot CLI — servers are available immediately, no restart needed.

## Factory (droid)

```bash
niro mcp install --client factory
```

Runs `droid mcp add` (writes `~/.factory/mcp.json`) and appends a reminder to
`~/.factory/AGENTS.md`. droid reloads automatically when the config file changes.

## Goose

```bash
niro mcp install --client goose
```

Writes an `extensions.niro` entry into `~/.config/goose/config.yaml` (Windows:
`%APPDATA%\Block\goose\config\config.yaml`). Restart Goose (or start a new session) after.

If your `config.yaml` already has an unusual `extensions:` layout, the installer prints the
YAML block to paste in by hand instead of guessing at a risky merge.

## OpenCode

```bash
niro mcp install --client opencode
```

Writes `~/.config/opencode/opencode.json` (`mcp.niro`) and appends a reminder to
`~/.config/opencode/AGENTS.md`. Restart OpenCode after.

## Cline

```bash
niro mcp install --client cline
```

Writes Cline's `cline_mcp_settings.json` (under VS Code's `globalStorage` for Cline's
publisher id) and adds a global rule file to Cline's Rules directory.

## Kiro

```bash
niro mcp install --client kiro
```

Writes `~/.kiro/settings/mcp.json` with `autoApprove: ["*"]` (safe — niro's tools are
read-only) and adds a global steering file at `~/.kiro/steering/niro.md`. Kiro reconnects MCP
servers automatically when you save the config.

## Antigravity

```bash
niro mcp install --client antigravity
```

Writes `~/.gemini/config/mcp_config.json`. Reload via **Agent Settings → Customizations →
Installed MCP Servers → Refresh** (or `/mcp` in the Antigravity CLI).

---

## Test it

After connecting any client, restart it (where noted above) and ask:

> "What calls `chargeCard()`? Use Niro tools."
> "What breaks if I change the `Invoice` schema?"
> "Is there existing code that parses webhooks, before I write a new one?"

If the assistant answers from the graph instead of grepping files, you're connected.

## Disconnect

```bash
niro mcp uninstall --client <id>     # one client
niro mcp uninstall --all -y          # every client, no confirm
```

`mcp uninstall` is the exact inverse of `mcp install` for each client — it only removes what
install added, leaving your own config, rules, and other MCP servers untouched. See the main
[README](../README.md#scenario-11--disconnect-an-ai-assistant-uninstall-the-mcp) for details.