# https://github.com/neon-solutions/add-mcp Project Manual
Generated at: 2026-06-06 08:13:16 UTC
## Table of Contents
- [Overview & Supported Agents](#page-1)
- [Commands Reference](#page-2)
- [Architecture & Programmatic API](#page-3)
- [Configuration, Registries & Troubleshooting](#page-4)
## Overview & Supported Agents
### Related Pages
Related topics: [Commands Reference](#page-2)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)
- [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json)
- [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md)
- [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts)
- [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
- [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md) *(referenced via release notes in community context)*
# Overview & Supported Agents
## Purpose and Scope
`add-mcp` is a single-command CLI (and library) for installing Model Context Protocol (MCP) servers into a wide range of AI coding agents. The project description in [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) states: *"Add MCP servers to your favorite coding agents with a single command."* The same file declares the `add-mcp` binary at `dist/index.js` and exposes a programmatic entry point at `./dist/lib.js`, which surfaces a `detect` / `upsert` / `remove` API introduced in `v1.10.0` for use as a library.
The core responsibility of the tool is to abstract away the per-agent configuration differences — file format, key naming (`mcpServers` vs `mcp_servers` vs nested structures), project vs. global scope, and config-file location — so a user can install the same MCP server across multiple agents with one command. The CLI also provides a `find` subcommand that searches curated registry entries (see [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts) for the `FindCommandOptions` and `FindInstallPlan` types) to discover and install servers from a registry.
## Supported Agents
The project ships support for twelve first-party targets, each with a known project-level and global-level configuration file. The authoritative mapping is maintained in the agent table in [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md):
| Agent | CLI alias | Project config path | Global config 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` |
| MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or `~/.mcporter/mcporter.jsonc`) |
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
| Windsurf | `windsurf` | - | `~/.codeium/windsurf/mcp_config.json` |
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/...` |
Source: [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md). The list of supported agents is also reflected in the `keywords` field of [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json), which advertises `antigravity`, `cline`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `gemini-cli`, `goose`, `mcporter`, `opencode`, `vscode`, `windsurf`, and `zed`.
The Windsurf target was added in `v1.10.3` and accepts the aliases `codeium` and `cascade` (per the release notes cited in the community context). GitHub Copilot CLI support was a long-standing community request (issue #4) because the `vscode` target previously only wrote `.vscode/mcp.json` locally and did not target the Copilot CLI's global config at `~/.copilot/mcp-config.json`.
## Recent Evolution and Programmatic Use
The repository evolves quickly; the latest release at the time of writing is `v1.10.4`, which added a `-h` shorthand for the `--header` flag ([CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)). Notable recent milestones referenced in the community evidence include:
- **`v1.10.0`** — exposed a programmatic API (`detect` / `upsert` / `remove`) and switched publishing to npm Trusted Publishing (OIDC) with provenance attestation.
- **`v1.10.2`** — fixed command targets containing absolute, home-relative, dot-relative, or Windows drive paths so they stay intact as the single executable command, addressing the space-in-path regression reported in issue #29 (e.g. macOS `.app` bundles such as `/Applications/Hopper Disassembler.app/...`).
- **`v1.10.3`** — added `windsurf` support with the aliases `codeium` and `cascade` ([PR #31](https://github.com/neon-solutions/add-mcp/pull/31)).
- **`v1.10.4`** — added `-h` shorthand for `--header`.
The programmatic surface is declared in [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) under `exports`, exposing `./dist/lib.js` as an ESM module with TypeScript types at `./dist/lib.d.ts`. The `find` subsystem, defined in [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts), exports types such as `FindCommandOptions`, `FindInstallPlan`, `RegistryServerEntry`, and `RegistrySearchResult`, enabling library consumers to integrate registry search and install planning into their own tooling.
The repository also includes a curated [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json) conforming to the official MCP server schema (`https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json`). This registry lists servers such as `io.sanity.www/mcp`, `io.github.getsentry/sentry-mcp`, `dev.firecrawl/mcp`, `com.netlify/mcp`, `io.github.vercel/next-devtools-mcp`, `com.render/mcp`, `com.resend/mcp`, `app.linear/linear`, `io.github.microsoft/playwright-mcp`, `io.github.railwayapp/mcp-server`, `com.upstash/mcp-server`, `com.vercel/vercel-mcp`, `io.github.browserbase/mcp-server-browserbase`, and others, each annotated with `packages` (npm, OCI/Docker) or `remotes` (streamable-http, SSE) descriptors.
## Known Limitations and Community Requests
A few recurring community concerns shape how users should think about agent coverage:
- **Windows / MSIX-installed Claude Desktop** (issue #50): the paths `add-mcp` writes to do not match the layout used by Claude Desktop when installed as an MSIX package on Windows. Workarounds require manual path correction.
- **Spaces in command paths** (issue #29): partially mitigated by `v1.10.2`, but absolute or dot-relative paths with spaces should still be tested against the target agent.
- **Empty `--env` values** (issue tracked in `v1.9.1`): the CLI now rejects `--env "KEY="` with an empty value and hints at shell expansion when a `${VAR}` placeholder was likely consumed by the shell.
- **Removal API** (issue #16): a `remove` subcommand for uninstalling deprecated MCP entries has been requested; a programmatic `remove` is now available via the library API.
- **LM Studio support** (issue #24): not yet shipped; the proposed config path is `~/.lmstudio/mcp.json`.
The development workflow is documented in [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) and [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md), which prescribe `bun` as the package manager, `bun run typecheck`, `bun run test`, and `bun run fmt` as the standard pre-PR quality pass, with `fallow` available as a complexity and dead-code linter.
## See Also
- [Installation & Quick Start](installation-and-quick-start.md) *(if available)*
- [Registry Format Reference](registry-format.md) *(if available)*
- [Programmatic API](programmatic-api.md) *(if available)*
---
## Commands Reference
### Related Pages
Related topics: [Overview & Supported Agents](#page-1), [Architecture & Programmatic API](#page-3), [Configuration, Registries & Troubleshooting](#page-4)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)
- [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/index.ts)
- [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts)
- [src/types.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts)
- [src/source-parser.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/source-parser.ts)
- [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
# Commands Reference
`add-mcp` is a single-binary CLI published to npm that installs and manages Model Context Protocol (MCP) servers for many coding agents from one command surface. According to [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json), it ships as the `add-mcp` executable (`bin.add-mcp`) and is also exposed as a programmatic library through `exports."."` (`./dist/lib.js` plus `./dist/lib.d.ts`). The package is `1.10.4` at the time of writing and targets Node `>=18`. Supported agent targets listed in the `keywords` block include `antigravity`, `cline`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `gemini-cli`, `goose`, `mcporter`, `opencode`, `vscode`, `windsurf`, and `zed`.
This page documents the command surface of `add-mcp`: the default "add" command, `list`, `find`, the shared global flags, and the programmatic library API.
## Command Surface Overview
The CLI is structured around four user-facing entry points: the default add command (invoked when no subcommand is given), `list`, `find`, and the built-in `--help` / `--version` machinery. Source: [src/index.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/index.ts). The command parser is `commander` (`v13.1.0`), and interactive prompts are produced with `@clack/prompts` (`v0.9.1`) per [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json).
```mermaid
flowchart LR
A[add-mcp invocation] --> B{Subcommand?}
B -- none --> C[add: install server]
B -- list --> D[list: enumerate servers]
B -- find --> E[find: search registries]
C --> F[(agent config file)]
D --> F
E --> G[registry.json + custom registries]
```
## Default Command: Install a Server
The default behavior installs an MCP server into one or more agent configurations. The source string can be a URL, an npm/PyPI/OCI package name, or a local command path. Source: [src/source-parser.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/source-parser.ts) defines `SourceType = "remote" | "package" | "command"` and a `ParsedSource` value, and the README's usage examples show URLs, packages, and local commands all routed through the same entry point.
```bash
# Remote HTTP/SSE server
npx add-mcp https://mcp.example.com/mcp
# Package install
npx add-mcp @upstash/mcp-server
# Local stdio command (macOS .app path with a space is preserved as one command)
npx add-mcp -g "/Applications/My App/bin/server" --name my-server
```
The space-in-path handling is a regression-tested behavior introduced in `v1.10.2`: command targets that look like absolute, home-relative, dot-relative, or Windows drive paths stay intact as the single executable command instead of being split on whitespace. Source: [v1.10.2 release notes](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.2) and the discussion in [issue #29](https://github.com/neon-solutions/add-mcp/issues/29).
### Common Flags for the Add Command
These flags are shared by `add` and (where relevant) `find`. The full description is in [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md).
| Flag | Description |
| --- | --- |
| `-g`, `--global` | Write to the user's global config for the target agent instead of the project-local one. |
| `-a`, `--agent ` | Restrict the install to a specific agent (one of the keywords listed in `package.json`). |
| `-n`, `--name ` | Override the inferred server name. |
| `-e`, `--env KEY=VALUE` | Add an environment variable. `--env "KEY="` (empty value) is rejected since `v1.9.1`. |
| `--header "Name: Value"` | Add an HTTP header for remote transports. `-h` is the shorthand added in `v1.10.4`. |
| `--args ...` | Append extra argv to a stdio command. |
`--header` and `--env` accept `${VAR}` placeholders; in interactive mode (`v1.9.0`) `add-mcp` prompts for each unique variable and omits skipped optional keys from the written config. Source: [v1.9.0](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.0) and [v1.9.1](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1) release notes.
## `list`
`list` enumerates MCP servers already configured for detected agents. From [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md):
```bash
# All detected agents in the current project
npx add-mcp list
# Global configs
npx add-mcp list -g
# One specific agent (shown even if not auto-detected)
npx add-mcp list -a cursor
```
This is the most direct answer to community request [issue #16](https://github.com/neon-solutions/add-mcp/issues/16) ("add remove mcp ability"): it surfaces the current inventory of servers per agent, which is the prerequisite to any removal workflow. Removal itself is exposed through the programmatic API described below.
## `find`
`find` searches a registry of curated MCP servers and installs the chosen entry. The bundled `registry.json` follows the [official MCP server schema](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json) and includes entries such as `io.github.getsentry/sentry-mcp`, `dev.firecrawl/mcp`, `com.resend/mcp`, `com.render/mcp`, and `io.github.upstash/mcp-server`. Source: [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json).
During a `find` install, `add-mcp` prompts for any declared `environmentVariables`, `headers`, and `packageArguments` (named flags are preserved as `flag` + `value` argv pairs, positional order is preserved). Source: [v1.9.0 release notes](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.0).
Custom registries are configured under `findRegistries` in `~/.config/add-mcp/config.json`. The CLI sends `GET` to the configured `url` with `search` (lowercased), `version=latest`, and `limit=100`, and expects `{ "servers": [ { "server": { ... } } ] }` in return. Source: [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md).
## Programmatic API (Library Use)
Since `v1.10.0` the package can be imported as a library. Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) (`"main": "./dist/lib.js"`, `"types": "./dist/lib.d.ts"`, `"exports": { ".": { "types": "./dist/lib.d.ts", "import": "./dist/lib.js" } }`) and [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts). The exposed surface is three functions:
- `detect(...)` — return which agents are installed and where their config files live.
- `upsert(...)` — add or update a single server entry (the equivalent of the default CLI command).
- `remove(...)` — delete a server entry by name, addressing the gap raised in [issue #16](https://github.com/neon-solutions/add-mcp/issues/16).
`McpServerConfig` and `TransportType` from [src/types.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts) describe the in-memory shape (`type`, `url`, `headers`, `command`, `args`, `env`), and `AgentConfig` carries per-agent metadata such as `configKey`, `format`, `supportedTransports`, `detectGlobalInstall`, and an optional `transformConfig` that agents use to rewrite a generic server into their own dialect (for example, Windsurf writes to `~/.codeium/windsurf/mcp_config.json` under `mcpServers`; source: [v1.10.3 release notes](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.3)).
## See Also
- [Configuration & Agent Matrix](README.md) — full per-agent config path table
- [Registry & `findRegistries`](README.md) — how to add a custom registry
- [Releasing](docs/RELEASING.md) — npm Trusted Publishing pipeline used to ship `add-mcp`
- Community: [issue #16](https://github.com/neon-solutions/add-mcp/issues/16) (remove), [issue #29](https://github.com/neon-solutions/add-mcp/issues/29) (paths with spaces), [issue #50](https://github.com/neon-solutions/add-mcp/issues/50) (Claude Desktop MSIX), [issue #51](https://github.com/neon-solutions/add-mcp/issues/51) (remote HTTP auth)
---
## Architecture & Programmatic API
### Related Pages
Related topics: [Commands Reference](#page-2), [Configuration, Registries & Troubleshooting](#page-4)
Related Source Files
The following source files were used to generate this page:
- [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json)
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)
- [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md)
- [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts)
- [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts)
- [src/installer.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/installer.ts)
- [src/agents.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/agents.ts)
- [src/formats/index.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/formats/index.ts)
- [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
# Architecture & Programmatic API
## Overview
`add-mcp` is a Node.js CLI for installing Model Context Protocol (MCP) servers into a growing list of coding agents. Beyond its interactive command-line interface, the project ships a **programmatic library API** so that other tools, scripts, and build pipelines can perform the same install, detect, and remove operations without spawning a subprocess.
The package targets `node >= 18` and is distributed as a dual-purpose artifact: a CLI binary named `add-mcp` *and* a typed ESM library published through npm with provenance attestation. Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json).
## High-Level Architecture
The repository is organized so the same business logic powers both the CLI and the library. The TypeScript sources under `src/` are bundled with `tsup` into a small set of ESM artifacts in `dist/`, and the relevant `package.json` fields make both surfaces available to consumers.
```mermaid
flowchart LR
A[src/index.ts
CLI entry] --> B[src/lib.ts
Library API]
B --> C[src/installer.ts]
A --> C
C --> D[src/agents.ts]
C --> E[src/formats/*]
C --> F[src/find.ts]
B --> F
D --> G[Agent config files
JSON / JSONC / TOML / YAML]
```
The build script `tsup src/index.ts src/lib.ts --format esm --dts --clean` produces both the CLI and the library bundles in one step, and `prepublishOnly: npm run build` ensures the published artifact is always freshly built. Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json).
## Programmatic API Surface
Starting with **v1.10.0**, `add-mcp` exposes a stable programmatic API in addition to the CLI. The release notes call out three named operations: `detect`, `upsert`, and `remove`. These let consumers identify which agents are available on a machine, install or update an MCP server entry, and clean up deprecated entries — all without invoking the binary. Source: [v1.10.0 release notes](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.0).
The library is consumed through the package's `main` / `types` fields, declared in `package.json`:
| Field | Value |
| --- | --- |
| `type` | `module` (ESM only) |
| `main` | `./dist/lib.js` |
| `types` | `./dist/lib.d.ts` |
| `exports["."].import` | `./dist/lib.js` |
| `exports["."].types` | `./dist/lib.d.ts` |
| `bin.add-mcp` | `dist/index.js` |
Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json).
The development conventions documented in [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) and [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md) emphasize that behavior changes must be covered by **unit tests without mocks** and **end-to-end tests without mocks**. This testing philosophy carries over to the library API: every public function should be exercised against a real temporary config tree, rather than faked agents or formatters.
### Common Library Use Cases
- **Build-time agent setup.** A scaffolding tool can call `upsert` to register a project-specific MCP server into the user's Cursor or VS Code config without forking the CLI.
- **Cleanup scripts.** [Issue #16](https://github.com/neon-solutions/add-mcp/issues/16) requests the ability to remove a deprecated MCP server. The library's `remove` operation (introduced in v1.10.0) makes it possible to write uninstall scripts that do not depend on shell parsing.
- **Custom installers.** Wrappers can read the result of `detect` to know which agents are actually present and target only those — useful when shipping a "setup" script that should not write to agents the user has not installed.
## Internal Module Responsibilities
Although the library is the primary new surface, the same internal modules back the CLI:
- **`src/find.ts`** defines the registry data model and the search/install planner. Public types include `RegistryServerEntry`, `RegistryPackageDefinition`, `RegistryRemoteDefinition`, `FindCommandOptions`, `FindInstallPlan`, `FindRegistrySearchConfig`, `PromptField`, `FailedRegistryInfo`, and `RegistrySearchResult`. The helper `buildPlaceholderValue` produces the `` / `` sentinels used when prompting for required secrets. Source: [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts).
- **`src/installer.ts`** is the orchestrator that takes a `FindInstallPlan` or a directly-supplied spec and writes it to the correct agent file in the right format.
- **`src/agents.ts`** resolves the supported agent list and the project-vs-global config path for each agent. It is the source of truth for the `claude-code`, `cursor`, `vscode`, `opencode`, `codex`, `windsurf`, `zed`, `claude-desktop`, `gemini-cli`, `goose`, `mcporter`, and `github-copilot-cli` identifiers. Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) (keywords array).
- **`src/formats/`** is a pluggable format layer. JSON, JSONC, TOML, and YAML are all supported, which is why the dependency list pulls in `@iarna/toml`, `js-yaml`, and `jsonc-parser`. Source: [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json).
- **`src/lib.ts`** re-exports the public surface (including the `detect` / `upsert` / `remove` functions) and is the file consumers import.
## Supported Agents and Config Paths
The library's `detect` and `upsert` operations both need to know which agents to consider. The following table is the canonical set shipped today (per the README) and represents the agent IDs the API understands. Source: [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md).
| Agent | CLI alias | Project config | Global config |
| --- | --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.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 `.jsonc`) |
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
| Windsurf | `windsurf` | — | `~/.codeium/windsurf/mcp_config.json` |
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/...` |
The `keywords` array in `package.json` enumerates the same identifier set and is what the CLI uses to validate user-supplied agent names. The registry that backs the `find` flow is the bundled [`registry.json`](https://github.com/neon-solutions/add-mcp/blob/main/registry.json) plus user-supplied registries declared in `FindRegistrySearchConfig`. Source: [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts).
## Community Considerations
Several community discussions shape how the programmatic API is consumed:
- **Removing servers** ([issue #16](https://github.com/neon-solutions/add-mcp/issues/16)) is the most-requested library operation; the `remove` function in v1.10.0 addresses it.
- **Spaces in server paths** ([issue #29](https://github.com/neon-solutions/add-mcp/issues/29)) caused a regression where `add-mcp "/Applications/My App/bin/server"` was naively split on whitespace. The fix in **v1.10.2** keeps absolute, home-relative, dot-relative, and Windows drive paths intact as a single executable command — important for the library to round-trip through its own reader/writer pair. Source: [v1.10.2 release notes](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.2).
- **Empty environment values** ([v1.9.1](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1)) are now rejected with a hint that a `${VAR}` may have been eaten by the shell. Library callers should treat these as thrown errors rather than silently writing broken config.
- **Authentication for remote HTTP** ([issue #51](https://github.com/neon-solutions/add-mcp/issues/51)) requests OAuth scope, auth provider, and timeout support for `streamable-http` remotes; the library is the natural place to surface these new options once they land.
- **New agent onboarding** continues — Windsurf landed in **v1.10.3** and LM Studio is requested in [issue #24](https://github.com/neon-solutions/add-mcp/issues/24). Library consumers should treat the agent list as a moving target and rely on `detect` rather than hard-coding identifiers.
## See Also
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) — full CLI usage and agent reference
- [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) / [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md) — development conventions and PR workflow
- [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md) — user-facing changes per release
- [docs/RELEASING.md](https://github.com/neon-solutions/add-mcp/blob/main/docs/RELEASING.md) — npm Trusted Publishing (OIDC) release process
---
## Configuration, Registries & Troubleshooting
### Related Pages
Related topics: [Overview & Supported Agents](#page-1), [Commands Reference](#page-2), [Architecture & Programmatic API](#page-3)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)
- [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json)
- [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
- [src/types.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts)
- [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md)
- [scripts/verify-registry.ts](https://github.com/neon-solutions/add-mcp/blob/main/scripts/verify-registry.ts)
- [scripts/sort-registry.ts](https://github.com/neon-solutions/add-mcp/blob/main/scripts/sort-registry.ts)
# Configuration, Registries & Troubleshooting
`add-mcp` is a CLI that installs [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers into the configuration files of multiple AI coding agents. The project is shipped as an ESM-only Node.js package (`"type": "module"`) and exposes both a binary (`bin.add-mcp` → `dist/index.js`) and a programmatic library API (`main`/`types` → `dist/lib.js` / `dist/lib.d.ts`) `Source: [package.json:1-25]()`. This page covers how the tool models per-agent configuration, how its curated registry is structured and maintained, and the recurring failure modes that surface in community discussions.
## Agent Configuration Model
### Supported Agents and Config Locations
`add-mcp` recognizes a fixed set of agent identifiers, exposed both as CLI positional arguments and as keywords in `package.json`. The keyword list in `package.json` enumerates the canonical set: `antigravity`, `cline`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `gemini-cli`, `goose`, `mcporter`, `opencode`, `vscode`, `windsurf`, and `zed` `Source: [package.json:30-45]()`. The README documents the per-agent on-disk paths and formats. Examples (truncated from the README table):
| Agent | Identifier | Local config path | Global config path |
| --- | --- | --- | --- |
| 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 `.jsonc`) |
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
| Windsurf | `windsurf` | — | `~/.codeium/windsurf/mcp_config.json` |
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/...` |
`Source: [README.md:1-25]()` (table rows). Windsurf is a recent addition; aliases `codeium` and `cascade` are accepted for the same target (release v1.10.3).
### Agent Configuration Type Model
The internal model for an agent is captured by the `AgentConfig` interface in `src/types.ts`. It encodes the on-disk representation that `add-mcp` reads and writes:
```ts
interface AgentConfig {
configKey: string; // dot-notation key in the file
localConfigKey?: string; // optional separate project key
format: ConfigFormat; // json, jsonc, toml, yaml
supportedTransports: ("stdio" | "sse" | "http")[];
unsupportedTransportMessage?: string;
detectGlobalInstall: () => Promise;
resolveConfigPath?: (...) => string;
transformConfig?: (serverName, config, { local }) => unknown;
}
```
`Source: [src/types.ts:1-42]()`
A server entry that `add-mcp` writes is normalized into the `McpServerConfig` shape, which is intentionally transport-agnostic:
```ts
interface McpServerConfig {
type?: "sse" | "http"; // remote transports
url?: string;
headers?: Record;
command?: string; // stdio local server
args?: string[];
env?: Record;
}
```
`Source: [src/types.ts:55-65]()`
The `transformConfig` hook lets each agent shape the normalized config into its own conventions (for example, Codex's TOML layout, Goose's YAML layout, or VS Code's `mcpServers` map). Per-agent `detectGlobalInstall()` is used to decide whether the agent supports user-level installs, which is the signal for selecting the global config path.
## Registry System
### Curated Registry Structure
`registry.json` is the in-repo source of truth for servers that can be installed with `add-mcp ` (the `find`/`install` commands) without the user having to provide an explicit URL or package name. Each entry follows the upstream MCP server schema (`$schema: https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json`) and wraps a `server` object `Source: [registry.json:1-25]()`. A representative entry exposes the fields the CLI consumes:
- `name` — unique registry identifier (for example `io.github.getsentry/sentry-mcp`, `com.descope/docs-mcp`, `dev.e2b/mcp-server`).
- `title`, `description` — display strings used in interactive pickers.
- `repository` — `{ url, source, subfolder? }` pointing at the upstream project.
- `version` — pinned upstream version.
- `packages[]` — installable distributions with `registryType` (`npm`, `oci`, …), `identifier`, `version`, `runtimeHint`, and `transport`. Environment variable requirements are declared inline as `environmentVariables[]` with `isRequired` and `isSecret` flags `Source: [registry.json:25-60]()`.
- `remotes[]` — optional hosted transports (for example `streamable-http` URLs for Sentry at `https://mcp.sanity.io`, Resend, Render, Vercel, Notion) with header requirements such as `Authorization: Bearer ` `Source: [registry.json:60-110]()`.
- `icons[]`, `websiteUrl` — presentational metadata.
The schema allows a server to declare **either** a stdio package, a remote URL, or both. `add-mcp` honors the first available form that matches the requested transport (the per-agent `supportedTransports` list in `src/types.ts` is what gates which form is allowed for a given target).
### Registry Maintenance Scripts
Two project-local scripts keep `registry.json` healthy, both wired into `package.json`:
- `registry:sort` — `tsx scripts/sort-registry.ts`. Canonicalizes ordering so diffs stay minimal.
- `registry:verify` — `tsx scripts/verify-registry.ts`. Validates schema compliance, uniqueness of `name`, and that referenced identifiers and URLs are well-formed.
`Source: [package.json:55-65]()` and `Source: [scripts/verify-registry.ts:1-20]()`. New server submissions follow the issue template used in community requests such as `Add Packrift MCP server to registry` ([issue #35](https://github.com/neon-solutions/add-mcp/issues/35)), where the proposed registry name and required environment variables are supplied up front.
## Programmatic API and Release Surface
Since v1.10.0, `add-mcp` is also a library. The package exports (`"."`) point at the ESM build with bundled TypeScript declarations `Source: [package.json:8-20]()`. The published programmatic surface is documented in the release notes as three functions: `detect` (test for global agent install), `upsert` (write or update an MCP server entry), and `remove` (delete an entry). Releases are produced by a locked-down GitHub Actions pipeline using npm Trusted Publishing (OIDC) with provenance attestation; there is no supported `npm publish` from a developer laptop `Source: [CLAUDE.md:1-10]()`.
## Common Failure Modes and Troubleshooting
Community-reported issues cluster around four classes of failure. Each has a documented cause and (where available) a fixed release.
### Paths Containing Spaces
`add-mcp` historically split the command argument on whitespace, which corrupted absolute paths such as `/Applications/Hopper Disassembler.app/.../HopperMCPServer` into `command: "/Applications/Hopper"` with the rest leaked into `args` ([issue #29](https://github.com/neon-solutions/add-mcp/issues/29)). The fix in v1.10.2 keeps command targets whole whenever they are absolute, home-relative (`~/...`), dot-relative (`./`, `../`), or Windows drive-relative paths. Users on older versions can work around this by either escaping the space in the shell (`/Applications/Hopper\ Disassembler.app/...`) or by quoting the path with `--name`; upgrading to ≥ 1.10.2 is the durable resolution.
### Claude Desktop Installed as MSIX on Windows
When Claude Desktop is installed as an MSIX package on Windows, the user-profile directory layout differs from the MSI install, so the global config path that `add-mcp` writes to is not where Claude Desktop reads from ([issue #50](https://github.com/neon-solutions/add-mcp/issues/50)). The workaround documented in the issue is to use the per-project local config (`add-mcp ... -l`) and then move or symlink the generated entry, or to install Claude Desktop via the standard MSI/WinGet distribution.
### Empty `--env` / `--header` Values and Shell Expansion
A subtle class of bug: a value like `--env "KEY="` used to be silently written, which produced a server entry that the agent immediately rejected at runtime. v1.9.1 rejects empty values up front. The same release also added shell-expansion hints to the error message for `--header "Key: ${UNSET}"` style invocations, since shells often eat unquoted `${VAR}` placeholders before the CLI sees them `Source: [release notes v1.9.1]()`. If you see an error about an empty value, quote your variable references (`'Key: '"'${UNSET}'"`-style or use the interactive prompt) rather than relying on a default.
### Authentication for Remote HTTP Servers
Remote servers declared under `remotes[]` in `registry.json` already include required headers (for example Render requires `Authorization: Bearer ` `Source: [registry.json:60-75]()`). When a server requires OAuth scopes or a custom `authProviderType`, those cannot be expressed through the current `headers: Record` shape; this is tracked in [issue #51](https://github.com/neon-solutions/add-mcp/issues/51). Until that is resolved, the supported workaround is to install the server into an agent that natively supports the desired auth flow and to inject the bearer token via a regular `--header "Authorization: Bearer "` invocation.
### Removing a Server
`add-mcp` is primarily an installer, but community demand exists for a clean removal path ([issue #16](https://github.com/neon-solutions/add-mcp/issues/16)). As of v1.10.4 the documented CLI surface is still install-oriented; library consumers can call the exported `remove` function, and CLI users can hand-edit the per-agent config file (the file paths in the table above are stable and the JSON/TOML/YAML layout is human-readable).
### Adding a New Agent Target
Several feature requests propose additional agents: GitHub Copilot CLI was added for global installs under `~/.copilot/mcp-config.json` ([issue #4](https://github.com/neon-solutions/add-mcp/issues/4)), and LM Studio (`~/.lmstudio/mcp.json`) is still open ([issue #24](https://github.com/neon-solutions/add-mcp/issues/24)). To support a new target, an entry is added to the agent registry in `src/agents` (modeled by `AgentConfig` in `src/types.ts`) with its `configKey`, `format`, `supportedTransports`, `detectGlobalInstall`, and any `transformConfig` needed to match the agent's preferred schema.
## See Also
- [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) — full CLI usage and flag reference
- [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) — keywords, scripts, exports
- [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json) — curated server list
- [docs/RELEASING.md](https://github.com/neon-solutions/add-mcp/blob/main/docs/RELEASING.md) — Trusted Publishing release runbook
- [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md) — user-facing change history
- [issue #16](https://github.com/neon-solutions/add-mcp/issues/16), [issue #24](https://github.com/neon-solutions/add-mcp/issues/24), [issue #29](https://github.com/neon-solutions/add-mcp/issues/29), [issue #35](https://github.com/neon-solutions/add-mcp/issues/35), [issue #50](https://github.com/neon-solutions/add-mcp/issues/50), [issue #51](https://github.com/neon-solutions/add-mcp/issues/51) — community discussions cited above
---
---
## Pitfall Log
Project: neon-solutions/add-mcp
Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.
## 1. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_a249cc57446f4702b71205d7038f7364 | https://github.com/neon-solutions/add-mcp/issues/35
## 2. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_482e954ed77d4d81aef0eef2d4e3a3e3 | https://github.com/neon-solutions/add-mcp/issues/50
## 3. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp
## 4. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp
## 5. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp
## 6. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp
## 7. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_09d1044faf824f248317ee044ca27240 | https://github.com/neon-solutions/add-mcp/issues/51
## 8. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp
## 9. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp