FAQ

Answers to common questions about using add-mcp to install MCP servers.

General Questions

What are MCP servers?

Model Context Protocol (MCP) servers extend your coding agent’s capabilities by providing:

Tools: Functions the agent can call (e.g., database queries, API calls)
Resources: Data sources the agent can access (e.g., file systems, documentation)
Context: Additional information to improve agent responses

MCP servers can:

Integrate with external services (Notion, Linear, GitHub, Slack)
Connect to databases (PostgreSQL, MySQL, MongoDB)
Provide file system access in a controlled way
Offer specialized tools for your workflow

Example use cases:

Query your production database while coding
Search and update Notion pages from your editor
Fetch GitHub issues and create pull requests
Access company-specific tools and APIs

Learn more at modelcontextprotocol.io

What coding agents does add-mcp support?

add-mcp supports 10 popular coding agents:

Agent	Project Support	Global Support
Claude Code	✓	✓
Claude Desktop	-	✓
Codex	✓	✓
Cursor	✓	✓
Gemini CLI	✓	✓
Goose	-	✓
GitHub Copilot CLI	✓	✓
OpenCode	✓	✓
VS Code	✓	✓
Zed	✓	✓

View all supported agents:

npx add-mcp list-agents

Agent aliases:

gemini → gemini-cli
github-copilot → vscode

How does add-mcp detect which agents I have installed?

add-mcp uses smart detection based on your installation scope:Project mode (default):

Looks for project-level config directories in current directory:
- .cursor/ for Cursor
- .vscode/ for VS Code
- .mcp.json or .claude/ for Claude Code
- opencode.json or .opencode/ for OpenCode
- .codex/ for Codex
- .gemini/ for Gemini CLI
- .zed/ for Zed
Automatically selects detected agents by default

Global mode (with -g flag):

Checks for agent installations in your home directory:
- ~/.cursor/ for Cursor
- ~/.config/opencode/ for OpenCode
- ~/.claude/ for Claude Code
- ~/Library/Application Support/Claude/ for Claude Desktop
- ~/.codex/ for Codex
- And more…
Selects all detected global agents by default

If no agents detected:

Interactive mode: Prompts you to select from all available agents
With --yes flag: Installs to all project-capable agents (project mode) or all agents (global mode)

You can always override detection with -a or --all flags.

Installation Scope

When should I use project vs global scope?

Project scope (default):

npx add-mcp https://mcp.example.com/mcp

Best for:

Project-specific servers (e.g., your app’s database)
Servers your team should also have
Committed to version control
Configuration that varies by project

Config location: .cursor/mcp.json, .vscode/mcp.json, etc.

Global scope (with -g flag):

npx add-mcp https://mcp.example.com/mcp -g

Best for:

Personal servers used across all projects
Tools you always want available
Not committed to version control
Global utilities (weather, calculator, etc.)

Config location: ~/.cursor/mcp.json, ~/.config/opencode/opencode.json, etc.

Pro tip: You can use both! Install project-specific servers locally and personal utilities globally.

# Project: team's database server
npx add-mcp @modelcontextprotocol/server-postgres -y

# Global: your personal GitHub integration
npx add-mcp mcp-server-github -g -y

Should I commit MCP config files to git?

Project-level configs (.cursor/mcp.json, etc.):

YES, commit them if the server is needed by your team
NO, add to .gitignore if they contain:
- Personal API keys or tokens
- Local-only server configurations
- Machine-specific paths

Use the --gitignore flag to automatically add config files to .gitignore:

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

Global configs (~/.cursor/mcp.json, etc.):

Never committed (they’re in your home directory)
Personal to your machine

Best practice:

Commit project configs with placeholder values
Document required environment variables
Use .gitignore for configs with secrets

Server Management

Can I install an MCP server to multiple agents at once?

Yes! There are several ways to install to multiple agents:1. Use the --all flag:

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

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

2. Specify multiple agents with -a flag:

npx add-mcp https://mcp.example.com/mcp -a cursor -a vscode -a opencode

3. Let smart detection select multiple agents:

# If you have .cursor/ and .vscode/ in your project:
npx add-mcp https://mcp.example.com/mcp -y
# Installs to both Cursor and VS Code automatically

4. Interactive selection:

# Without -y flag, you can select from a list
npx add-mcp https://mcp.example.com/mcp
# → Shows checkboxes to select multiple agents

The installation runs in parallel, so all agents are configured simultaneously.

How do I update an MCP server to a new version?

Simply run add-mcp again with the same server name:

# Install initial version
npx add-mcp @modelcontextprotocol/server-postgres

# Update to latest version (run the same command)
npx add-mcp @modelcontextprotocol/server-postgres

What happens:

add-mcp overwrites the existing server configuration
The server name remains the same
New version will be used next time agent loads

For remote servers with version in URL:

# Change URL to new version
npx add-mcp https://mcp.example.com/v2/mcp --name example-server

Use custom name to prevent overwriting:

# Keep both versions
npx add-mcp @modelcontextprotocol/server-postgres --name postgres-old
npx add-mcp @modelcontextprotocol/server-postgres --name postgres-new

Don’t forget to restart your agent after updating!

What happens if a server name already exists?

The existing server configuration is overwritten without warning.Example:

# First installation
npx add-mcp https://old.example.com/mcp --name my-server

# Second installation - OVERWRITES the first one
npx add-mcp https://new.example.com/mcp --name my-server

To avoid accidental overwrites:

Use different names:

npx add-mcp https://api1.example.com/mcp --name api-prod
npx add-mcp https://api2.example.com/mcp --name api-staging

Check existing config first:

# View current servers
cat .cursor/mcp.json

# Or use jq to list server names
cat .cursor/mcp.json | jq '.mcpServers | keys[]'

Back up before installing:

cp .cursor/mcp.json .cursor/mcp.json.backup
npx add-mcp https://mcp.example.com/mcp --name my-server

Pro tip: The overwrite behavior is useful for updating servers (see previous FAQ).

How do I remove an MCP server?

add-mcp currently does not have a built-in remove/uninstall command.To remove a server, manually edit the config file:

Locate the config file:

# Project level
.cursor/mcp.json
.vscode/mcp.json
.mcp.json
opencode.json

# Global level
~/.cursor/mcp.json
~/.config/opencode/opencode.json
~/.claude.json

Open in editor:

code .cursor/mcp.json
# or
vim ~/.cursor/mcp.json

Remove the server entry:

{
  "mcpServers": {
    "server-to-keep": { ... },
    "server-to-remove": { ... },  // ← Delete this line
    "another-server": { ... }
  }
}

Save and restart your agent

For YAML configs (Goose):

extensions:
  - name: server-to-remove  # ← Delete this entire block
    type: streamable_http
    uri: https://...
  - name: server-to-keep
    type: stdio

For TOML configs (Codex):

[mcp_servers.server-to-remove]  # ← Delete this section
url = "https://..."

[mcp_servers.server-to-keep]
command = "npx"

Transport Types

Which transport type should I use?

For remote MCP servers:

Transport	When to Use	Flag
HTTP (default)	Most modern remote servers	`--transport http` (or omit)
SSE	Legacy servers, explicit requirement	`--transport sse`

# Default HTTP (recommended for new servers)
npx add-mcp https://mcp.example.com/mcp

# Explicit HTTP
npx add-mcp https://mcp.example.com/mcp --transport http

# Use SSE if server requires it
npx add-mcp https://mcp.example.com/sse --transport sse

For local npm packages/commands:

stdio transport is always used automatically
No need to specify transport type

# Always uses stdio
npx add-mcp @modelcontextprotocol/server-postgres
npx add-mcp "node /path/to/server.js"

Agent compatibility:

Most agents support all transport types
Exception: Claude Desktop only supports stdio via config file
- Use Settings → Connectors in the app for remote servers

Aliases:

--type is an alias for --transport
Both flags work identically

npx add-mcp https://mcp.example.com/mcp --type sse
# Same as:
npx add-mcp https://mcp.example.com/mcp --transport sse

What's the difference between HTTP and SSE transport?

HTTP (Streamable HTTP):

Modern, recommended transport
Uses standard HTTP with streaming responses
Better error handling and connection management
Supported by all agents (except Claude Desktop config)
Default in add-mcp

SSE (Server-Sent Events):

Legacy transport type
Deprecated by MCP specification but still widely used
One-way streaming from server to client
Supported by all agents (except Claude Desktop config)
Use only if server explicitly requires it

stdio (Standard Input/Output):

For local processes only
Used automatically for npm packages and commands
Most secure (no network exposure)
Supported by all agents

Performance comparison:

HTTP and SSE have similar performance for most use cases
stdio is fastest (no network overhead)
Choose based on server requirements, not performance

Advanced Usage

Can I use custom HTTP headers for authentication?

Yes! Use the --header flag for remote servers:

# Bearer token authentication
npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer sk_1234567890"

# API key authentication
npx add-mcp https://mcp.example.com/mcp \
  --header "X-API-Key: your-api-key"

# Multiple headers
npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer TOKEN" \
  --header "X-Custom-Header: value" \
  --header "X-Another-Header: value2"

Use environment variables:

# Reference environment variable in header
npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

# Or use shell substitution
npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.api-token)"

Header format requirements:

Format: "Key: Value" (colon with space)
Must be quoted if it contains spaces or special characters
Can be repeated for multiple headers

Supported by all agents:

Headers are written to config file
Agent sends headers with each MCP request
Works with both HTTP and SSE transports

Note: Headers are only applicable to remote servers, not local stdio servers.

How do I install with custom server names?

Use the --name flag to specify a custom server name:

# Default: inferred from URL or package name
npx add-mcp https://mcp.context7.com/mcp
# Server name: "context7"

# Custom name
npx add-mcp https://mcp.context7.com/mcp --name my-context
# Server name: "my-context"

When to use custom names:

Multiple instances of same server:

npx add-mcp @modelcontextprotocol/server-postgres --name postgres-prod
npx add-mcp @modelcontextprotocol/server-postgres --name postgres-staging

Descriptive names for your team:

npx add-mcp https://api.example.com/mcp --name company-api-prod
npx add-mcp https://staging.example.com/mcp --name company-api-staging

Avoid name conflicts:

# If "github" already exists
npx add-mcp mcp-server-github --name github-personal

Name requirements:

Can contain letters, numbers, hyphens, underscores
Should be unique within each agent’s config
Will overwrite existing server with same name

Can I skip all confirmation prompts?

Yes! Use the -y or --yes flag:

# Skip all prompts
npx add-mcp https://mcp.example.com/mcp -y

# Useful for CI/CD and scripts
npx add-mcp @modelcontextprotocol/server-postgres --all -y

# Combine with other flags
npx add-mcp https://mcp.example.com/mcp -g -a cursor -y

What gets skipped:

Agent selection (uses detected agents or all agents)
Installation scope confirmation
Final installation confirmation

Behavior with --yes:

Smart detection still runs
Uses detected agents automatically
If no agents detected:
- Project mode: Installs to all project-capable agents
- Global mode: Installs to all agents

Use cases:

Automated setup scripts
CI/CD pipelines
Batch installations
When you know exactly what you want

Example automation script:

#!/bin/bash
# Setup script for new project

# Install required MCP servers
npx add-mcp @modelcontextprotocol/server-postgres -y
npx add-mcp https://mcp.company.com/api -y --header "Authorization: Bearer $TOKEN"
npx add-mcp mcp-server-github --all -y

# Add to gitignore
npx add-mcp https://mcp.private.com/mcp -y --gitignore

Troubleshooting

Where can I find help if something goes wrong?

If you encounter issues:

Check the Troubleshooting guide:
- See Troubleshooting page for common issues
Search existing issues:
- github.com/neondatabase/add-mcp/issues
Create a new issue with:
- Operating system and version
- Exact command you ran
- Complete error message
- Output of npx add-mcp list-agents
- Agent name and version
- Relevant config files (remove sensitive data)
Check agent-specific documentation:
- Some agents have specific MCP requirements
- Consult your agent’s docs for MCP configuration
Verify the MCP server itself:
- Test if the server works independently
- Check server documentation for requirements

Get Started

Usage

Configuration

Advanced

General Questions

Installation Scope

Server Management

Transport Types

Advanced Usage

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Usage

Configuration

Advanced

​General Questions

​Installation Scope

​Server Management

​Transport Types

​Advanced Usage

​Troubleshooting

Build docs developers (and LLMs) love

General Questions

Installation Scope

Server Management

Transport Types

Advanced Usage

Troubleshooting