Installation Scopes

add-mcp supports two installation scopes: project and global. The scope determines where MCP server configurations are stored and how they’re shared.

Overview

Scope	Flag	Config Location	Use Case	Committed to Git
Project	(default)	`.cursor/mcp.json`, `.vscode/mcp.json`, etc.	Shared with team, project-specific servers	Yes (recommended)
Global	`-g`	`~/.cursor/mcp.json`, `~/.config/opencode/opencode.json`, etc.	Personal servers, available across all projects	No

Project Scope (Default)

Project scope installs MCP servers to configuration files within your project directory.

Characteristics

Location: Config files in project directories (.cursor/, .vscode/, .mcp.json, etc.)
Shared: Committed with your project to version control
Use Case: Team collaboration, project-specific MCP servers
Default Behavior: Automatically used when -g flag is omitted

Example Project Paths

project-root/
├── .cursor/
│   └── mcp.json          # Cursor project config
├── .vscode/
│   └── mcp.json          # VS Code / GitHub Copilot CLI project config
├── .mcp.json             # Claude Code project config
├── .codex/
│   └── config.toml       # Codex project config
├── .gemini/
│   └── settings.json     # Gemini CLI project config
├── .zed/
│   └── settings.json     # Zed project config
└── opencode.json         # OpenCode project config

Installation

# Install to project (default)
npx add-mcp https://mcp.example.com/mcp

# Explicitly specify project agents
npx add-mcp https://mcp.example.com/mcp -a cursor -a vscode

# Install to all detected project agents
npx add-mcp https://mcp.example.com/mcp -y

Smart Detection (Project Mode)

When you run add-mcp without -g, the CLI automatically detects project-level agents:

Scans the current directory for project config directories and files
Detects agents with existing project configurations
Pre-selects detected agents for installation
Shows all project-capable agents for manual selection

Detection Example: If your project has .cursor/ and .vscode/ directories:

$ npx add-mcp https://mcp.example.com/mcp
✓ Detected 2 agents
? Select agents to install to
  ✓ Cursor (project · detected)
  ✓ VS Code (project · detected)
  ○ Claude Code (project)
  ○ OpenCode (project)
  # ...

When to Use Project Scope

Team Projects: Share MCP server configurations with your team
Project-Specific Servers: MCP servers that are relevant to a specific project
Version Control: Config should be committed and versioned
Reproducibility: Ensure all team members have the same MCP setup

Global Scope (`-g` flag)

Global scope installs MCP servers to user-level configuration files in your home directory.

Characteristics

Location: Config files in home directory (~/, ~/.config/, etc.)
Shared: Personal to your user account, not committed to Git
Use Case: Personal MCP servers, available across all projects
Activation: Use the -g or --global flag

Example Global Paths

~/ (Home Directory)
├── .cursor/
│   └── mcp.json                                    # Cursor global config
├── .claude.json                                    # Claude Code global config
├── .codex/
│   └── config.toml                                 # Codex global config
├── .gemini/
│   └── settings.json                               # Gemini CLI global config
├── .copilot/
│   └── mcp-config.json                             # GitHub Copilot CLI global config
├── .config/
│   ├── opencode/
│   │   └── opencode.json                           # OpenCode global config
│   └── goose/
│       └── config.yaml                             # Goose global config
└── Library/Application Support/                    # macOS
    ├── Claude/
    │   └── claude_desktop_config.json              # Claude Desktop global config
    ├── Code/
    │   └── User/
    │       └── mcp.json                            # VS Code global config
    └── Zed/
        └── settings.json                           # Zed global config

Installation

# Install globally
npx add-mcp https://mcp.example.com/mcp -g

# Install globally to specific agents
npx add-mcp https://mcp.example.com/mcp -g -a cursor -a claude-code

# Install globally to all agents
npx add-mcp https://mcp.example.com/mcp -g --all -y

Smart Detection (Global Mode)

When you run add-mcp -g, the CLI automatically detects globally-installed agents:

Scans your home directory for agent installation directories
Detects all agents installed on your system (including global-only agents)
Pre-selects detected agents for installation
Shows all agents for manual selection

Detection Example: If you have Cursor, Claude Desktop, and VS Code installed:

$ npx add-mcp https://mcp.example.com/mcp -g
✓ Detected 3 agents
? Select agents to install to
  ✓ Cursor (global · detected)
  ✓ Claude Desktop (global · detected)
  ✓ VS Code (global · detected)
  ○ Claude Code (global)
  ○ OpenCode (global)
  # ...

When to Use Global Scope

Personal Servers: MCP servers you use across all projects
Development Tools: Testing and development MCP servers
Private Credentials: Servers requiring personal API keys or credentials
Cross-Project Availability: Servers needed in every project

Global-Only Agents

Two agents only support global installation:

Claude Desktop

Global Path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Project Support: None
Note: Always installs globally, even without -g flag

Goose

Global Path: ~/.config/goose/config.yaml (Linux/macOS) or %APPDATA%\Block\goose\config\config.yaml (Windows)
Project Support: None
Note: Always installs globally, even without -g flag

Scope Selection

When you don’t specify -g and select agents that support project configuration, add-mcp will prompt you to choose the scope:

$ npx add-mcp https://mcp.example.com/mcp -a cursor
? Installation scope
  > Project - Install in current directory (committed with your project)
    Global - Install in home directory (available across all projects)

Skip the Prompt

Use -y to automatically use the default scope:

# Default to project scope
npx add-mcp https://mcp.example.com/mcp -y

# Default to global scope
npx add-mcp https://mcp.example.com/mcp -g -y

Mixed Scope Installations

When you select multiple agents, some may only support global config (like Claude Desktop and Goose), while others support both:

$ npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-desktop --all

Installation Summary
  Server: example
  Type: remote
  Scope: Mixed (project + global)
    Project: Cursor
    Global: Claude Desktop

add-mcp will automatically route each agent to the appropriate scope based on their capabilities.

Version Control Recommendations

Project Scope - Commit to Git

Project configurations should be committed to version control:

# These should be committed
git add .cursor/mcp.json
git add .vscode/mcp.json
git add .mcp.json
git add opencode.json
git commit -m "Add MCP server configurations"

Global Scope - Don’t Commit

Global configurations should NOT be committed to version control. They’re stored in your home directory and won’t be in your project.

.gitignore Support

Use the --gitignore flag to automatically add project config files to .gitignore if you don’t want to commit them:

# Add config files to .gitignore
npx add-mcp https://mcp.example.com/mcp --gitignore

Note: --gitignore only works with project-scoped installations. It’s ignored when used with -g.

Detection Logic

The smart detection system uses different strategies based on scope:

Project Detection

From detectProjectAgents() in agents.ts:381-397:

function detectProjectAgents(cwd?: string): AgentType[] {
  const dir = cwd || process.cwd();
  const detected: AgentType[] = [];

  for (const [type, config] of Object.entries(agents)) {
    if (!config.localConfigPath) continue;  // Skip global-only agents

    for (const detectPath of config.projectDetectPaths) {
      if (existsSync(join(dir, detectPath))) {
        detected.push(type as AgentType);
        break;
      }
    }
  }

  return detected;
}

Project detection checks:

.cursor directory → Cursor
.vscode directory → VS Code, GitHub Copilot CLI
.mcp.json file → Claude Code
.codex directory → Codex
.gemini directory → Gemini CLI
.zed directory → Zed
opencode.json or .opencode → OpenCode

Global Detection

From detectAllGlobalAgents() in agents.ts:399-409:

async function detectAllGlobalAgents(): Promise<AgentType[]> {
  const detected: AgentType[] = [];

  for (const [type, config] of Object.entries(agents)) {
    if (await config.detectGlobalInstall()) {
      detected.push(type as AgentType);
    }
  }

  return detected;
}

Global detection checks agent-specific directories:

~/.cursor → Cursor
~/Library/Application Support/Claude → Claude Desktop (macOS)
~/.codex → Codex
~/.gemini → Gemini CLI
~/.config/goose/config.yaml → Goose
~/.copilot → GitHub Copilot CLI
~/.config/opencode → OpenCode
~/Library/Application Support/Code/User → VS Code (macOS)
~/Library/Application Support/Zed → Zed (macOS)
Platform-specific paths for Linux and Windows

Examples

Project Installation

# Install to detected project agents
npx add-mcp @modelcontextprotocol/server-postgres

# Install to specific project agents
npx add-mcp https://mcp.example.com/mcp -a cursor -a vscode

# Install to all project-capable agents
npx add-mcp https://mcp.example.com/mcp -y

# Install and add config to .gitignore
npx add-mcp https://mcp.example.com/mcp --gitignore

Global Installation

# Install globally to detected agents
npx add-mcp https://mcp.example.com/mcp -g

# Install globally to specific agents
npx add-mcp https://mcp.example.com/mcp -g -a claude-code -a cursor

# Install globally to all agents
npx add-mcp https://mcp.example.com/mcp -g --all -y

Mixed Installation

# Some agents go to project, some to global (based on support)
npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-desktop
# Result: Cursor → project, Claude Desktop → global

Agents - See which agents support project vs global config
Transports - Learn about HTTP, SSE, and stdio transports

Get Started

Usage

Configuration

Advanced

Installation Scopes

Installation Scopes

Overview

Project Scope (Default)

Characteristics

Example Project Paths

Installation

Smart Detection (Project Mode)

When to Use Project Scope

Global Scope (`-g` flag)

Characteristics

Example Global Paths

Installation

Smart Detection (Global Mode)

When to Use Global Scope

Global-Only Agents

Claude Desktop

Goose

Scope Selection

Skip the Prompt

Mixed Scope Installations

Version Control Recommendations

Project Scope - Commit to Git

Global Scope - Don’t Commit

.gitignore Support

Detection Logic

Project Detection

Global Detection

Examples

Project Installation

Global Installation

Mixed Installation

Build docs developers (and LLMs) love

Get Started

Usage

Configuration

Advanced

​Installation Scopes

​Overview

​Project Scope (Default)

​Characteristics

​Example Project Paths

​Installation

​Smart Detection (Project Mode)

​When to Use Project Scope

​Global Scope (-g flag)

​Characteristics

​Example Global Paths

​Installation

​Smart Detection (Global Mode)

​When to Use Global Scope

​Global-Only Agents

​Claude Desktop

​Goose

​Scope Selection

​Skip the Prompt

​Mixed Scope Installations

​Version Control Recommendations

​Project Scope - Commit to Git

​Global Scope - Don’t Commit

​.gitignore Support

​Detection Logic

​Project Detection

​Global Detection

​Examples

​Project Installation

​Global Installation

​Mixed Installation

​Related Pages

Build docs developers (and LLMs) love

Installation Scopes

Overview

Project Scope (Default)

Characteristics

Example Project Paths

Installation

Smart Detection (Project Mode)

When to Use Project Scope

Global Scope (`-g` flag)

Characteristics

Example Global Paths

Installation

Smart Detection (Global Mode)

When to Use Global Scope

Global-Only Agents

Claude Desktop

Goose

Scope Selection

Skip the Prompt

Mixed Scope Installations

Version Control Recommendations

Project Scope - Commit to Git

Global Scope - Don’t Commit

.gitignore Support

Detection Logic

Project Detection

Global Detection

Examples

Project Installation

Global Installation

Mixed Installation

Related Pages