Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neon-solutions/add-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Every MCP server installation made by add-mcp is written to a config file in one of two scopes: project-level or global. The scope determines which directory the config file lives in and, by extension, who the server is available to — just you, or the whole team.

​
Scope comparison

Project scope

Config is written inside the current directory (e.g. .cursor/mcp.json). Typically committed with the repository so every team member gets the MCP server automatically.

Global scope

Config is written to a path in the user home directory (e.g. ~/.cursor/mcp.json). Available across every project on the machine, but only for the current user.
ScopeFlagExample locationBest for
Project(default).cursor/mcp.jsonCommitting to the repo, sharing with teammates
Global-g / --global~/.cursor/mcp.jsonPersonal tooling, cross-project access

​
Default behavior: project scope

When you run add-mcp without -g, it operates in project scope. If the current directory contains agent config files (like .cursor/, .vscode/, or .mcp.json), add-mcp detects them and pre-selects those agents in the interactive prompt. The server config is then written to the project-level path for each detected agent. 
# Installs to project-level configs of all detected agents
npx add-mcp https://mcp.example.com/mcp

​
Global scope with -g

Add the -g or --global flag to write configs to the user home directory instead. Global mode scans for globally installed agents (by checking their home-directory config paths and binary presence) and pre-selects them: 
# Installs to global configs of all detected agents
npx add-mcp https://mcp.example.com/mcp -g

# Non-interactive global install to a specific agent
npx add-mcp https://mcp.example.com/mcp -g -a claude-code -y

​
Agents that only support global scope

Some agents do not have a project-level config file. For these agents, add-mcp always writes to their global config path regardless of whether -g is passed:

Global-only agents

  • Antigravity
  • Cline VSCode Extension (cline)
  • Cline CLI (cline-cli)
  • Claude Desktop
  • Windsurf
  • Goose

Project + global agents

All other agents — Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, MCPorter, OpenCode, VS Code, and Zed — support both scopes.

​
Mixed routing

When you install to multiple agents at once, add-mcp routes each one individually. Project-capable agents receive a project-level config; global-only agents receive a global config — all in a single command. You will see each agent’s resolved path in the output so there is no ambiguity about where files were written. 
# Cursor gets .cursor/mcp.json; Windsurf gets ~/.codeium/windsurf/mcp_config.json
npx add-mcp https://mcp.example.com/mcp -a cursor -a windsurf -y

​
The --gitignore flag

By default, project-level config files are meant to be committed with the repository. If you want the MCP server available locally without sharing it with the team, pass --gitignore to append every generated project config path to .gitignore automatically: 
# Install to Cursor project config but do not commit it
npx add-mcp https://mcp.example.com/mcp -a cursor -y --gitignore
add-mcp only appends entries that are not already present in .gitignore, and creates the file if it does not exist.
The --gitignore flag affects project-scope installs only. Global config files live in the home directory and are never added to any .gitignore.

​
Choosing a scope

Use project scope (default) when the MCP server is part of the project’s development workflow and you want teammates to have access immediately after cloning. Use global scope (-g) for personal productivity tools or servers that are not tied to a specific repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us