Content
# add-mcp
Add MCP servers to your favorite coding agents with a single command.
Supports **Claude Code**, **Codex**, **Cursor**, **OpenCode**, **VSCode** and [9 more](#supported-agents).
## Install an MCP Server
```bash
npx add-mcp url | package name [options]
```
Example installing the Context7 MCP server:
```bash
npx add-mcp https://mcp.context7.com/mcp
```
### Usage Examples
```bash
# 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) |
```bash
# 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
**With `-g` (global mode):**
- Detects all globally-installed agents (including Claude Desktop, Codex, Zed)
- Selects detected agents by default
- Shows detected agents plus all other supported agents for selection
**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.
Header support is available for remote installs across all supported agents.
## Supported Agents
MCP servers can be installed to any of these agents:
| Agent | `--agent` | Project Path | Global Path |
| ---------------------- | -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| Antigravity | `antigravity` | - | `~/.gemini/antigravity/mcp_config.json` |
| Cline VSCode Extension | `cline` | - | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Cline CLI | `cline-cli` | - | `~/.cline/data/settings/cline_mcp_settings.json` |
| 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` |
| MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) |
| 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:** `cline-vscode` → `cline`, `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](#smart-detection) for details.
## What are MCP Servers?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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
Connection Info
You Might Also Like
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.