How add-mcp Auto-Detects AI Agents: Smart Detection

When you run add-mcp without specifying an agent, it doesn’t ask you to pick from a blank list — it scans your environment first. This smart detection step finds which AI coding agents are active in your current directory (or on your machine globally) and pre-selects them in the interactive prompt, so the right agents are already checked before you press Enter.

How detection works

Detection logic differs based on whether you are installing in project scope (the default) or global scope (-g).

Project mode (default)
Global mode (-g)
No agents detected

add-mcp scans the current directory for agent config markers. Each agent has a set of paths it looks for — for example, Cursor is detected when .cursor/ exists, Claude Code when .mcp.json or .claude/ is present, and VS Code / GitHub Copilot CLI when .vscode/ exists.Detected agents appear at the top of the multi-select list with a project hint and are pre-checked. You can deselect them or add others before confirming.Detected project markers by agent:

Agent	Detection paths
Claude Code	`.mcp.json`, `.claude/`
Codex	`.codex/`
Cursor	`.cursor/`
Gemini CLI	`.gemini/`
GitHub Copilot CLI	`.vscode/`
MCPorter	`config/mcporter.json`
OpenCode	`opencode.json`, `.opencode/`
VS Code	`.vscode/`
Zed	`.zed/`

Agents that are global-only (Antigravity, Cline, Cline CLI, Claude Desktop, Goose, Windsurf) are never detected in project mode but still appear in the list so you can select them manually.

When -g is passed, add-mcp checks for globally installed agents rather than project config files. Each agent has a detectGlobalInstall check — typically verifying that a known directory or config file exists in the home directory (e.g. ~/.cursor/, ~/.claude/, ~/.codeium/windsurf/).For agents like VS Code, Cline VSCode Extension, and Zed, detection checks for the presence of their application support directories. Goose is detected if its global YAML config file exists.Detected agents are pre-selected in the same multi-select prompt, this time with a global hint next to each one.

# Run in global mode — detects globally installed agents
npx add-mcp https://mcp.example.com/mcp -g

If add-mcp finds no agent markers in either project or global mode, the behavior depends on how the command is invoked:

Interactive mode: The prompt falls back to the last selection (see below). If there is no saved selection, all agents are shown unchecked and you choose manually.
With --yes (-y): add-mcp installs to all project-capable agents in project mode, or all global-capable agents in global mode, without prompting.

# No agents detected + --yes → installs to all applicable agents
npx add-mcp https://mcp.example.com/mcp -y

Last-selection memory

add-mcp remembers the agents you chose the last time you ran an install. This selection is persisted to ~/.config/add-mcp/config.json (respecting $XDG_CONFIG_HOME) and used as the default pre-selection the next time no agents are detected. In the multi-select prompt, previously chosen agents that were not detected in the current environment appear below detected agents with a · selected last time hint, making it easy to spot them.

The last-selection memory is used as a fallback only when no agents are detected. Detected agents always take priority and are pre-selected regardless of the saved state.

Bypassing detection explicitly

If you already know which agents you want, pass -a one or more times. This skips detection and the interactive prompt entirely:

# Bypass detection — install directly to Cursor and Claude Code
npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code

# Same, globally, non-interactive
npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code -g -y

The `--all` flag

--all installs to every supported agent at once, completely bypassing both detection and the interactive prompt:

# Install to all agents, project scope where supported
npx add-mcp mcp-server-github --all

# Install to all agents, globally, no prompts
npx add-mcp mcp-server-github --all -g -y

Use --all --gitignore when you want a broad install across all project-capable agents without committing any of the generated config files to version control.

npx add-mcp https://mcp.example.com/mcp --all --gitignore -y

Detection in the programmatic API

You can run the same detection logic from your own tooling using the exported functions:

import { detectProjectAgents, detectGlobalAgents } from "add-mcp";

// Returns AgentType[] of agents with project config in /my/project
const projectAgents = detectProjectAgents("/my/project");

// Returns AgentType[] of globally installed agents
const globalAgents = await detectGlobalAgents();

Both functions return an array of AgentType strings (e.g. ["cursor", "claude-code"]) that you can pass directly to upsertServer or use for any other purpose in your own CLI integrations.

Get Started

Commands

Concepts

Registries

Guides

How add-mcp Auto-Detects AI Agents: Smart Detection

How detection works

Last-selection memory

Bypassing detection explicitly

The `--all` flag

Detection in the programmatic API

​How detection works

​Last-selection memory

​Bypassing detection explicitly

​The --all flag

​Detection in the programmatic API

How detection works

Last-selection memory

Bypassing detection explicitly

The `--all` flag

Detection in the programmatic API