Skip to content
Back to search

add-mcp

The open MCP config tool - npx add-mcp

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/neon-solutions/add-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/neon-solutions/add-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neon-solutions--add-mcp/badge.svg)](/listings/neon-solutions--add-mcp)

HTML

<a href="/listings/neon-solutions--add-mcp"><img src="/api/listings/neon-solutions--add-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install an MCP server by remote URL or package name:

npx add-mcp url | package name [options]

Example installing the Context7 remote MCP server:

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

Example installing the Context7 remote MCP server via the programmatic API — great for integrating add-mcp in your own CLI tool:

import { upsertServer } from "add-mcp";

const result = upsertServer(
  "cursor",
  "context7",
  { type: "http", url: "https://mcp.context7.com/mcp" },
  { local: true },
);
console.log(result);

You can add env variables and arguments (stdio) and headers (remote) to the server config using the `--env`, `--args` and `--header` options. With `${VAR}` placeholders, interactive installs prompt for each variable (omit skipped optional keys so empty strings are not written to config).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 553 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # add-mcp
  2. Add MCP servers to your favorite coding agents with a single command.
  3. Supports **Claude Code**, **Codex**, **Cursor**, **OpenCode**, **VS Code**, **Grok Build** and [19 more](#supported-agents).
  4. Docs and registry: [add-mcp.com](https://add-mcp.com)
  5. ## Install an MCP Server
  6. Install an MCP server by remote URL or package name:
  7. ```bash
  8. npx add-mcp url | package name [options]
  9. ```
  10. Example installing the Context7 remote MCP server:
  11. ```bash
  12. npx add-mcp https://mcp.context7.com/mcp
  13. ```
  14. Example installing the Context7 remote MCP server via the programmatic API — great for integrating add-mcp in your own CLI tool:
  15. ```ts
  16. import { upsertServer } from "add-mcp";
  17. const result = upsertServer(
  18. "cursor",
  19. "context7",
  20. { type: "http", url: "https://mcp.context7.com/mcp" },
  21. { local: true },
  22. );
  23. console.log(result);
  24. ```
  25. You can add env variables and arguments (stdio) and headers (remote) to the server config using the `--env`, `--args` and `--header` options. With `${VAR}` placeholders, interactive installs prompt for each variable (omit skipped optional keys so empty strings are not written to config).
  26. ## Find MCP Servers
  27. Find and install MCP servers from the [add-mcp registry](https://add-mcp.com/registry):
  28. ```bash
  29. npx add-mcp find vercel
  30. ```
  31. The first `find`/`search` run automatically saves the add-mcp registry to `~/.config/add-mcp/config.json` (or `$XDG_CONFIG_HOME/add-mcp/config.json`). You can edit that file to replace the default registry, add the official Anthropic registry, or point at any registry-compatible server.
  32. ## Supported Agents
  33. MCP servers can be installed to any of these agents:
  34. | Agent | `--agent` | Project Path | Global Path |
  35. | ---------------------- | -------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
  36. | Antigravity | `antigravity` | - | `~/.gemini/config/mcp_config.json` (shared by Antigravity, Antigravity IDE, and Antigravity CLI) |
  37. | Cline VSCode Extension | `cline` | - | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
  38. | Cline CLI | `cline-cli` | - | `~/.cline/data/settings/cline_mcp_settings.json` |
  39. | Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` |
  40. | Claude Desktop | `claude-desktop` | - | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  41. | Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
  42. | Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
  43. | Factory Droid | `factory-droid` | `.factory/mcp.json` | `~/.factory/mcp.json` |
  44. | fx | `fx` | - | `~/.fx/mcp.json` |
  45. | Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` |
  46. | Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` |
  47. | GitHub Copilot CLI | `github-copilot-cli` | `.mcp.json` (or existing `.github/mcp.json`) | `$COPILOT_HOME/mcp-config.json` (defaults to `~/.copilot/mcp-config.json`) |
  48. | Grok Build | `grok-build` | `.grok/config.toml` | `$GROK_HOME/config.toml` (defaults to `~/.grok/config.toml`) |
  49. | Hermes Agent | `hermes` | - | `$HERMES_HOME/config.yaml` (defaults to `~/.hermes/config.yaml`, or the active profile) |
  50. | Junie | `junie` | `.junie/mcp/mcp.json` | `$JUNIE_HOME/mcp/mcp.json` (defaults to `~/.junie/mcp/mcp.json`, which the Junie JetBrains IDE plugin reads) |
  51. | Kilo Code | `kilo-code` | `kilo.json` (or existing `.kilo/`, `.kilocode/`, or root `kilo.jsonc` config) | `~/.config/kilo/kilo.json` (or existing `~/.config/kilo/kilo.jsonc`) |
  52. | Kimi Code | `kimi-code` | `.kimi-code/mcp.json` | `$KIMI_CODE_HOME/mcp.json` (defaults to `~/.kimi-code/mcp.json`) |
  53. | Kiro CLI | `kiro-cli` | `.kiro/settings/mcp.json` | `~/.kiro/settings/mcp.json` (shared with the Kiro IDE) |
  54. | Mastra Code | `mastracode` | `.mastracode/mcp.json` | `~/.mastracode/mcp.json` |
  55. | MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) |
  56. | OpenCode | `opencode` | `opencode.jsonc` (or existing `opencode.json` / `.opencode/` config) | `~/.config/opencode/opencode.jsonc` (or existing `opencode.json`) |
  57. | Pi | `pi` | `.pi/mcp.json` | `$PI_CODING_AGENT_DIR/mcp.json` (defaults to `~/.pi/agent/mcp.json`) |
  58. | VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
  59. | Windsurf | `windsurf` | - | `~/.codeium/windsurf/mcp_config.json` |
  60. | Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/settings.json` |
  61. **Aliases:** `codeium`, `cascade` → `windsurf`, `cline-vscode` → `cline`, `gemini` → `gemini-cli`, `github-copilot` → `vscode`, `grok` → `grok-build`, `kilo`, `kilocode` → `kilo-code`, `kimi` → `kimi-code`, `kiro` → `kiro-cli`, `mastra` → `mastracode`, `pi-agent` → `pi`
  62. Mastra Code also reads project `.mcp.json` for Claude Code compatibility. add-mcp writes `.mastracode/mcp.json` so a mixed Claude + Mastra install does not share that file.
  63. Pi has no built-in MCP. add-mcp writes the Pi-owned files [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) reads (`pi install npm:pi-mcp-adapter`). A running Pi session picks the change up after `/reload`.
  64. Kimi Code only loads a project-level `.kimi-code/mcp.json` after you trust the folder in the CLI, so a project install may not take effect until then.
  65. Junie CLI and the Junie JetBrains IDE plugin read the same `mcp.json`. The IDE plugin always reads `~/.junie/mcp/mcp.json`, so it only sees a global install when `JUNIE_HOME` is unset. Junie requires server names to match `^[a-zA-Z0-9_-]+$`, so keep `--name` within that pattern. Junie CLI sends an `Authorization` header from the config; the IDE plugin does not support tokens in MCP configs.
  66. Hermes Agent keeps MCP servers under `mcp_servers` in the same `config.yaml` as its other settings; add-mcp edits only that entry and keeps the file's comments. Without `HERMES_HOME`, add-mcp writes to the profile selected with `hermes profile use`. A running session picks the change up after `/reload-mcp`.
  67. fx reads MCP servers only from `~/.fx/mcp.json`. A project file cannot add a server. A running session applies the change with `/mcp reload`.
  68. OpenCode keeps the shape already in the file: `mcp.<name>` on a V1 or empty config, `mcp.servers.<name>` when that native map is already there. In a mixed file, a native entry wins over a legacy entry with the same name. Adding a new name to a mixed file still writes V1; renaming a server keeps it in the map it already uses.
  69. GitHub Copilot CLI project installs write `.mcp.json`. If `.mcp.json` is absent, an existing `.github/mcp.json` is reused. Copilot CLI does not read `.vscode/mcp.json` (that path is the VS Code agent). Entries left in `.vscode/mcp.json` from older Copilot CLI installs stay there for VS Code; rerun with `--agent github-copilot-cli` to write the CLI path. `.mcp.json` is shared with Claude Code: removing a server from either agent removes it for both. add-mcp will not create `.mcp.json` when `.github/mcp.json` already exists, because Copilot CLI would then ignore the GitHub file. Merge those servers into `.mcp.json` under `mcpServers` first. Copilot writes replace the file with strict JSON, so comments in that file are dropped (including global `~/.copilot/mcp-config.json`). Copilot CLI loads a project file only after the folder is trusted; confirm with `copilot mcp list --json`.
  70. ## Installation Scope
  71. | Scope | Flag | Location | Use Case |
  72. | ----------- | --------- | ----------------------- | --------------------------------------------- |
  73. | **Project** | (default) | `.cursor/mcp.json` etc. | Committed with your project, shared with team |
  74. | **Global** | `-g` | `~/.cursor/mcp.json` | Available across all projects |
  75. ## Smart Detection
  76. The CLI automatically detects agents based on your environment:
  77. **Default (project mode):**
  78. - Detects project-level config files (`.cursor/`, `.vscode/`, `.mcp.json`, etc.)
  79. - Selects detected agents (have project config in the current directory) by default
  80. - Shows detected agents plus all other supported agents for selection
  81. **With `-g` (global mode):**
  82. - Detects all globally-installed agents (including Claude Desktop, Codex, Zed)
  83. - Selects detected agents by default
  84. - Shows detected agents plus all other supported agents for selection
  85. **No agents detected:**
  86. - Interactive mode: Defaults to the last selection and shows all agents for selection
  87. - With `--yes`: Installs to all project-capable agents (project mode) or all global-capable agents (global mode)
  88. ## Commands
  89. Besides the implicit add command, `add-mcp` also supports the following commands:
  90. | Command | Description |
  91. | ------------- | ------------------------------------------------------------ |
  92. | `find` | Search MCP registry servers and install a selected match |
  93. | `search` | Alias for `find` |
  94. | `list` | List installed MCP servers across detected agents |
  95. | `remove` | Remove an MCP server from agent configurations |
  96. | `sync` | Synchronize server names and installations across agents |
  97. | `unify` | Alias for `sync` |
  98. | `list-agents` | List all supported coding agents with scope (project/global) |
  99. ## Add Command
  100. ### Usage Examples
  101. ```bash
  102. # Remote MCP server (streamable HTTP)
  103. npx add-mcp https://mcp.example.com/mcp
  104. # Remote MCP server (SSE transport)
  105. npx add-mcp https://mcp.example.com/sse --transport sse
  106. # Remote MCP server with auth header
  107. npx add-mcp https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"
  108. # Remote server; fx reads the bearer token from this env var
  109. npx add-mcp https://mcp.example.com/mcp --bearer-token-env NEON_API_KEY
  110. # Remote server with a request timeout and OAuth scopes
  111. # (each agent only keeps the fields it supports; others are dropped with a warning)
  112. npx add-mcp https://mcp.example.com/mcp --timeout 30000 --scopes "read,write"
  113. # Auto-approve all tools for agents that support it (Codex, Claude Code)
  114. npx add-mcp "executor mcp" --name executor -a codex -a claude-code --auto-approve
  115. # Auto-approve only selected tools
  116. npx add-mcp "executor mcp" --name executor -a codex --auto-approve --approve-tool execute
  117. # npm package (runs via npx)
  118. npx add-mcp @modelcontextprotocol/server-postgres
  119. # Non-interactive installation to all detected agents in the project directory
  120. npx add-mcp https://mcp.example.com/mcp -y
  121. # Non-interactive installation to the global Claude Code config
  122. npx add-mcp https://mcp.example.com/mcp -g -a claude-code -y
  123. # Full command with arguments
  124. npx add-mcp "npx -y @org/mcp-server --flag value"
  125. # Node.js script
  126. npx add-mcp "node /path/to/server.js --port 3000"
  127. # Local stdio server with environment variables (repeatable)
  128. npx add-mcp @modelcontextprotocol/server-filesystem --env "API_KEY=secret" --env "DATABASE_URL=postgres://localhost/app"
  129. # Install for Cursor and Claude Code
  130. npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code
  131. # Install with custom server name
  132. npx add-mcp @modelcontextprotocol/server-postgres --name postgres
  133. # Install to all supported agents
  134. npx add-mcp mcp-server-github --all
  135. # Install to all agents, globally, without prompts
  136. npx add-mcp mcp-server-github --all -g -y
  137. # Add generated config files to .gitignore
  138. npx add-mcp https://mcp.example.com/mcp -a cursor -y --gitignore
  139. ```
  140. ### Options
  141. | Option | Description |
  142. | --------------------------- | ---------------------------------------------------------------------------- |
  143. | `-g, --global` | Install to user directory instead of project |
  144. | `-a, --agent <agent>` | Target specific agents (e.g., `cursor`, `claude-code`). Can be repeated. |
  145. | `-t, --transport <type>` | Transport type for remote servers: `http` (default), `sse` |
  146. | `--type <type>` | Alias for `--transport` |
  147. | `-h, --header <header>` | HTTP header for remote servers (repeatable, `Key: Value`) |
  148. | `--bearer-token-env <name>` | Env var whose value fx sends as a bearer token (capability-gated, see below) |
  149. | `--env <env>` | Env var for local stdio servers (repeatable, `KEY=VALUE`) |
  150. | `--timeout <ms>` | Request timeout (ms) for remote servers (capability-gated, see below) |
  151. | `--scopes <scopes>` | OAuth scopes for remote servers, comma-separated (capability-gated) |
  152. | `--oauth-scopes <scopes>` | Alias for `--scopes` |
  153. | `--auto-approve` | Auto-approve MCP tool calls for supported agents (Codex, Claude Code) |
  154. | `--approve-tool <tool>` | Tool to auto-approve with `--auto-approve` (repeatable; defaults to all) |
  155. | `-n, --name <name>` | Server name (auto-inferred if not provided) |
  156. | `-y, --yes` | Skip all confirmation prompts |
  157. | `--all` | Install to all agents |
  158. | `--gitignore` | Add generated config files to `.gitignore` |
  159. #### Capability-gated fields (`--timeout`, `--scopes`, `--bearer-token-env`)
  160. Not every MCP client understands every field. `add-mcp` keeps one canonical
  161. server config and each agent declares which optional fields it supports, mapping
  162. them into that client's native shape:
  163. | Field | Flag | Supported by | Mapped to |
  164. | ------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
  165. | Timeout | `--timeout` | Claude Code, Factory Droid, Gemini CLI, Grok Build, Hermes Agent, Kilo Code, Kimi Code, Kiro CLI, Pi | `timeout` (milliseconds); Grok Build `tool_timeout_sec` (seconds), Hermes Agent `timeout` (seconds), Kimi Code `toolTimeoutMs`, Pi `requestTimeoutMs` |
  166. | OAuth scopes | `--scopes` | Cursor, Gemini CLI, Mastra Code | Cursor `auth.scopes`, Gemini and Mastra Code `oauth.scopes` |
  167. | Bearer token env | `--bearer-token-env` | fx | `bearer_token_env` |
  168. | Tool auto-approval | `--auto-approve` / `--approve-tool` | Codex, Claude Code | Codex approval modes; Claude Code permission allow rules |
  169. When you target an agent that does not support a field, `add-mcp` drops it from
  170. that agent's config and prints a warning (e.g. _"request timeout is not
  171. supported by VS Code; dropped from that config."_). Other agents still receive
  172. it. `--timeout`, `--scopes`, and `--bearer-token-env` apply to remote servers
  173. only; `--auto-approve` applies to both remote and local servers.
  174. When `--bearer-token-env` and `--header Authorization` are both set, fx omits
  175. the Authorization header and writes `bearer_token_env`. Other agents keep the
  176. header.
  177. #### Auto-approving tool calls (`--auto-approve`)
  178. `--auto-approve` preconfigures agent-level approval so the agent doesn't prompt
  179. before each MCP tool call — useful for servers that already gate actions
  180. internally. Use `--approve-tool <name>` (repeatable) to approve only specific
  181. tools; without it, all tools are approved.
  182. - **Codex** — writes approval modes into `config.toml`: per-tool
  183. `tools.<name>.approval_mode = "approve"`, or `default_tools_approval_mode = "approve"` for all tools.
  184. - **Claude Code** — writes permission allow rules to a separate settings file
  185. (`.claude/settings.local.json` for project installs, `~/.claude/settings.json`
  186. for global), e.g. `mcp__<server>__<tool>`, or `mcp__<server>` for all tools.
  187. The MCP server entry itself stays clean.
  188. > Note: Claude Code's all-tools rule (`mcp__<server>`) follows the documented
  189. > format, but a known Claude Code bug ([#34739](https://github.com/anthropics/claude-code/issues/34739))
  190. > can still prompt for non-fully-qualified MCP rules. Listing tools explicitly
  191. > with `--approve-tool` is the most reliable path there.
  192. ### Transport Types
  193. `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:
  194. | Transport | Flag | Description |
  195. | --------- | ------------------ | ----------------------------------------------------- |
  196. | **HTTP** | `--transport http` | Streamable HTTP (default) |
  197. | **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
  198. Local servers (npm packages, commands) always use **stdio** transport.
  199. Note that most agents like Cursor and opencode do not require the `type` information to be set.
  200. ## Find Command
  201. ### Usage Examples
  202. ```bash
  203. # Search for servers by keyword and choose one interactively
  204. npx add-mcp find vercel
  205. # Browse servers without a keyword
  206. npx add-mcp find
  207. # Use search alias (same as find)
  208. npx add-mcp search notion
  209. # Install a found server globally to a specific agent without prompts
  210. npx add-mcp find neon -a claude-code -g -y
  211. # Install to all agents and add generated project configs to .gitignore
  212. npx add-mcp find github --all --gitignore
  213. ```
  214. ### Options
  215. | Option | Description |
  216. | ----------------------- | ------------------------------------------------------------------------ |
  217. | `-g, --global` | Install to user directory instead of project |
  218. | `-a, --agent <agent>` | Target specific agents (e.g., `cursor`, `claude-code`). Can be repeated. |
  219. | `-n, --name <name>` | Server name override (defaults to the selected catalog entry name) |
  220. | `-y, --yes` | Skip confirmation prompts |
  221. | `--auto-approve` | Auto-approve MCP tool calls for supported agents (Codex, Claude Code) |
  222. | `--approve-tool <tool>` | Tool to auto-approve with `--auto-approve` (repeatable; defaults to all) |
  223. | `--all` | Install to all agents |
  224. | `--gitignore` | Add generated config files to `.gitignore` |
  225. Transport for `find`/`search` is inferred from registry metadata. The CLI prefers HTTP remotes when available and only falls back to SSE when HTTP is not available for the selected install context.
  226. When a server offers both remote and stdio package options, interactive mode lets you choose one (remote is the default). With `-y`, it auto-selects remote.
  227. If a selected remote server defines URL variables or header inputs:
  228. - required values must be provided
  229. - optional values can be skipped with Enter
  230. - with `-y`, placeholders are inserted (for example `<your-header-value-here>`)
  231. ### Configuring Registries for Find / Search
  232. The first time you run `find` or `search`, the CLI automatically saves the add-mcp registry to `~/.config/add-mcp/config.json` (respects `XDG_CONFIG_HOME`) and reuses that registry on every subsequent search.
  233. ### Built-in Registries
  234. | Registry | Base URL | Description |
  235. | ------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  236. | **add-mcp registry** | `https://add-mcp.com/registry/api/v1/servers` | MCP servers discovered by integrations.sh and exposed through an MCP registry-compatible API, using add-mcp's checked-in `registry.json` as the source of truth. |
  237. | **Official Anthropic registry** | `https://registry.modelcontextprotocol.io/v0.1/servers` | The community-driven MCP server registry maintained by Anthropic. Contains the broadest catalog of MCP servers. |
  238. > The add-mcp registry previously lived at `https://mcp.agent-tooling.dev/api/v1/servers`. That URL keeps working, and saved configs referencing it are migrated to the add-mcp.com address automatically on the next `find`/`search` run.
  239. ### Missing A Server in integrations.sh?
  240. The default add-mcp registry is generated from [integrations.sh](https://integrations.sh) and refreshed weekly. It includes every integrations.sh domain whose surface document lists an HTTPS MCP endpoint, including self-published listings. To be listed in add-mcp, add your MCP server to integrations.sh. Package-only servers, and remotes integrations.sh dropped that we still want in `find`, go in `registry.overlay.json`.
  241. Maintainers can refresh the checked-in registry snapshot with:
  242. ```bash
  243. bun run registry:sync # rebuild registry.json from integrations.sh plus the overlay
  244. bun run registry:verify # schema, ordering, and overlay checks (CI runs this)
  245. bun run registry:diff # markdown summary of added, removed, renamed, and changed servers vs origin/main
  246. ```
  247. ### Editing or Removing Registries
  248. Registry selections are stored in `~/.config/add-mcp/config.json` under the `findRegistries` key. You can edit this file directly to replace, add, remove, or reorder registries.
  249. Default add-mcp registry:
  250. ```json
  251. {
  252. "version": 1,
  253. "findRegistries": [
  254. {
  255. "url": "https://add-mcp.com/registry/api/v1/servers",
  256. "label": "add-mcp registry"
  257. }
  258. ]
  259. }
  260. ```
  261. Replace the default with the official Anthropic registry:
  262. ```json
  263. {
  264. "version": 1,
  265. "findRegistries": [
  266. {
  267. "url": "https://registry.modelcontextprotocol.io/v0.1/servers",
  268. "label": "Official Anthropic registry"
  269. }
  270. ]
  271. }
  272. ```
  273. Search both the add-mcp registry and the official Anthropic registry:
  274. ```json
  275. {
  276. "version": 1,
  277. "findRegistries": [
  278. {
  279. "url": "https://add-mcp.com/registry/api/v1/servers",
  280. "label": "add-mcp registry"
  281. },
  282. {
  283. "url": "https://registry.modelcontextprotocol.io/v0.1/servers",
  284. "label": "Official Anthropic registry"
  285. }
  286. ]
  287. }
  288. ```
  289. To reset to the default add-mcp registry, remove the `findRegistries` key or delete the config file.
  290. ### Adding a Custom Registry
  291. Any server that implements the registry API can be added as a custom entry. The CLI sends a `GET` request to the configured `url` with the following query parameters:
  292. | Parameter | Value |
  293. | --------- | -------------------------------------- |
  294. | `search` | The user's search keyword (lowercased) |
  295. | `version` | `latest` |
  296. | `limit` | `100` |
  297. The endpoint must return JSON in this shape:
  298. ```json
  299. {
  300. "servers": [
  301. {
  302. "server": {
  303. "name": "example-server",
  304. "description": "An example MCP server",
  305. "version": "1.0.0",
  306. "remotes": [
  307. {
  308. "type": "streamable-http",
  309. "url": "https://mcp.example.com/mcp"
  310. }
  311. ]
  312. }
  313. }
  314. ]
  315. }
  316. ```
  317. To add your own registry, append an entry to `findRegistries` in `~/.config/add-mcp/config.json`:
  318. ```json
  319. {
  320. "url": "https://my-registry.example.com/api/v1/servers",
  321. "label": "My custom registry"
  322. }
  323. ```
  324. ## List Command
  325. List installed MCP servers across detected agents:
  326. ```bash
  327. # List servers for all detected agents in the project
  328. npx add-mcp list
  329. # List global server configs
  330. npx add-mcp list -g
  331. # List servers for a specific agent (shown even if not detected)
  332. npx add-mcp list -a cursor
  333. ```
  334. | Option | Description |
  335. | --------------------- | -------------------------------------- |
  336. | `-g, --global` | List global configs instead of project |
  337. | `-a, --agent <agent>` | Filter to specific agent(s) |
  338. ## Remove Command
  339. Remove an MCP server from agent configurations by server name, URL, or package name:
  340. ```bash
  341. # Remove by server name (interactive selection by default)
  342. npx add-mcp remove neon
  343. # Remove all matches without prompting
  344. npx add-mcp remove neon -y
  345. # Remove by URL
  346. npx add-mcp remove https://mcp.neon.tech/mcp -y
  347. # Remove from global configs for a specific agent
  348. npx add-mcp remove neon -g -a cursor -y
  349. ```
  350. | Option | Description |
  351. | --------------------- | ------------------------------------ |
  352. | `-g, --global` | Remove from global configs |
  353. | `-a, --agent <agent>` | Filter to specific agent(s) |
  354. | `-y, --yes` | Remove all matches without prompting |
  355. ## Sync Command
  356. Synchronize server names and installations across all detected agents. Servers are grouped by URL or package name, and each group is unified to the shortest server name. Servers with conflicting headers, env, or args across agents are skipped with a warning.
  357. ```bash
  358. # Sync project-level configs (interactive confirmation)
  359. npx add-mcp sync
  360. # Sync without prompting
  361. npx add-mcp sync -y
  362. # Sync global configs
  363. npx add-mcp sync -g -y
  364. ```
  365. | Option | Description |
  366. | -------------- | -------------------------------------- |
  367. | `-g, --global` | Sync global configs instead of project |
  368. | `-y, --yes` | Skip confirmation prompts |
  369. `unify` is an alias for `sync`.
  370. ## Programmatic API
  371. ```ts
  372. import {
  373. detectProjectAgents,
  374. detectGlobalAgents,
  375. upsertServer,
  376. removeServer,
  377. listInstalledServers,
  378. } from "add-mcp";
  379. const project = detectProjectAgents("/path/to/project");
  380. const global = await detectGlobalAgents();
  381. // Remote server
  382. upsertServer(
  383. "claude-code",
  384. "example",
  385. { type: "http", url: "https://mcp.example.com/api" },
  386. { local: true, cwd: "/path/to/project" },
  387. );
  388. // Stdio (npm package)
  389. upsertServer("claude-code", "postgres", {
  390. command: "npx",
  391. args: ["-y", "@modelcontextprotocol/server-postgres"],
  392. });
  393. const projectServers = await listInstalledServers({
  394. cwd: "/path/to/project",
  395. });
  396. const globalServers = await listInstalledServers({ global: true });
  397. removeServer("claude-code", "example", {
  398. local: true,
  399. cwd: "/path/to/project",
  400. });
  401. ```
  402. `upsertServer` and `removeServer` return `{ success, path, error? }` rather than throwing.
  403. ## Troubleshooting
  404. ### Server not loading
  405. Some agents & editors like Claude Code require a restart to load the new MCP server. Otherwise, like Cursor, require you to navigate to the MCP settings page and toggle the new server as enabled.
  406. fx reads MCP servers only from `~/.fx/mcp.json`. A project file cannot add a server. A running session applies the change with `/mcp reload`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.