add-mcp

Add MCP servers to your favorite coding agents with a single command.

Supports Claude Code, Codex, Cursor, OpenCode, VSCode and 5 more.

Install an MCP Server

npx add-mcp url | package name [options]

Example installing the Context7 MCP server:

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

Usage Examples

# Remote MCP server (streamable HTTP)
npx add-mcp https://mcp.example.com/mcp

# Remote MCP server (SSE transport)
npx add-mcp https://mcp.example.com/sse --transport sse

# Remote MCP server with auth header
npx add-mcp https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"

# npm package (runs via npx)
npx add-mcp @modelcontextprotocol/server-postgres

# Non-interactive installation to all detected agents in the project directory
npx add-mcp https://mcp.example.com/mcp -y

# Non-interactive installation to the global Claude Code config
npx add-mcp https://mcp.example.com/mcp -g -a claude-code -y

# Full command with arguments
npx add-mcp "npx -y @org/mcp-server --flag value"

# Node.js script
npx add-mcp "node /path/to/server.js --port 3000"

# Install for Cursor and Claude Code
npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code

# Install with custom server name
npx add-mcp @modelcontextprotocol/server-postgres --name postgres

# Install to all supported agents
npx add-mcp mcp-server-github --all

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

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

Options

| Option | Description | | ------------------------ | ------------------------------------------------------------------------ | | -g, --global | Install to user directory instead of project | | -a, --agent <agent> | Target specific agents (e.g., cursor, claude-code). Can be repeated. | | -t, --transport <type> | Transport type for remote servers: http (default), sse | | --type <type> | Alias for --transport | | --header <header> | HTTP header for remote servers (repeatable, Key: Value) | | -n, --name <name> | Server name (auto-inferred if not provided) | | -y, --yes | Skip all confirmation prompts | | --all | Install to all agents | | --gitignore | Add generated config files to .gitignore |

Additional Commands

Besides the implicit add command, add-mcp also supports the following commands:

| Command | Description | | ------------- | ------------------------------------------------------------ | | list-agents | List all supported coding agents with scope (project/global) |

# List all supported agents
npx add-mcp list-agents

Installation Scope

| Scope | Flag | Location | Use Case | | ----------- | --------- | ----------------------- | --------------------------------------------- | | Project | (default) | .cursor/mcp.json etc. | Committed with your project, shared with team | | Global | -g | ~/.cursor/mcp.json | Available across all projects |

Smart Detection

The CLI automatically detects agents based on your environment:

Default (project mode):

• Detects project-level config files (.cursor/, .vscode/, .mcp.json, etc.)
• Selects detected agents (have project config in the current directory) by default
• Shows detected agents plus all other supported agents for selection
• Installs to project-level config files

With -g (global mode):

• Detects all globally-installed agents (including Claude Desktop, Codex, Zed)
• All agents use global config

No agents detected:

• Interactive mode: Defaults to the last selection and shows all agents for selection
• With --yes: Installs to all project-capable agents (project mode) or all global-capable agents (global mode)

Transport Types

add-mcp supports all three transport types: HTTP, SSE, and stdio. Some agents require type option to be set to specify the transport type. You can use the --type or --transport option to specify the transport type:

| Transport | Flag | Description | | --------- | ------------------ | ----------------------------------------------------- | | HTTP | --transport http | Streamable HTTP (default) | | SSE | --transport sse | Server-Sent Events (deprecated by MCP but still used) |

Local servers (npm packages, commands) always use stdio transport.

Note that some agents like Cursor and opencode do not require the type information to be set.

HTTP Headers

Use --header to pass custom headers for remote servers. The flag can be repeated. If you explicitly select agents that don't support headers, the install will error. Auto-detected installs skip unsupported agents with a warning.

Agents that support headers: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, OpenCode, VS Code, Zed. Agents that do not support headers: Goose.

Supported Agents

MCP servers can be installed to any of these agents:

| Agent | --agent | Project Path | Global Path | | ------------------ | -------------------- | ----------------------- | ----------------------------------------------------------------- | | Claude Code | claude-code | .mcp.json | ~/.claude.json | | Claude Desktop | claude-desktop | - | ~/Library/Application Support/Claude/claude_desktop_config.json | | Codex | codex | .codex/config.toml | ~/.codex/config.toml | | Cursor | cursor | .cursor/mcp.json | ~/.cursor/mcp.json | | Gemini CLI | gemini-cli | .gemini/settings.json | ~/.gemini/settings.json | | Goose | goose | .goose/config.yaml | ~/.config/goose/config.yaml | | GitHub Copilot CLI | github-copilot-cli | .vscode/mcp.json | ~/.copilot/mcp-config.json | | OpenCode | opencode | opencode.json | ~/.config/opencode/opencode.json | | VS Code | vscode | .vscode/mcp.json | ~/Library/Application Support/Code/User/mcp.json | | Zed | zed | .zed/settings.json | ~/Library/Application Support/Zed/settings.json |

Aliases: gemini → gemini-cli, github-copilot → vscode

The CLI uses smart detection to find agents in your project directory and globally installed agents. See Smart Detection for details.

What are MCP Servers?

Model Context Protocol (MCP) servers extend your coding agent's capabilities by providing tools, resources, and context. MCP servers can:

• Integrate with external services (Notion, Linear, GitHub, etc.)
• Connect to databases (PostgreSQL, MySQL, etc.)
• Provide file system access
• Offer specialized tools for your workflow

Troubleshooting

Server not loading

• Verify the server URL is correct and accessible
• Check the agent's MCP configuration file for syntax errors
• Ensure the server name doesn't conflict with existing servers

Permission errors

Ensure you have write access to the target configuration directory.

License

Apache 2.0