Related Pages

Related topics: CLI Commands Reference, Programmatic API and Registry Configuration

Overview and Supported Agents

Purpose and Scope of the Project

add-mcp is a Node.js command-line tool (published on npm under the name add-mcp) that registers a Model Context Protocol (MCP) server into the configuration file used by a chosen AI coding agent. Its role is to normalize the small but irritating differences between agents: where each agent stores its config, what JSON shape it uses, whether command and args are split or supplied as a single string, and whether the install is global or scoped to the current project. The CLI can also be consumed programmatically — since v1.10.0, the package exposes detect, upsert, and remove for use as a library in addition to the binary Source: README.md:Overview section Source: package.json:bin field.

A single invocation can target one or more agents in parallel: the user picks the agent(s) interactively when no flag is given, or supplies --client / --claude-desktop / --vscode / etc. directly. The CLI writes a new entry under mcpServers (or each agent's equivalent key) and, by default, leaves any pre-existing servers untouched. Beginning with v2.0.0, re-installing a server under an existing name replaces that server's whole entry instead of deep-merging new fields into the old one, which avoids stale hybrid configs after a server's transport changes Source: CHANGELOG / release notes for v2.0.0.

Supported Agents

The set of supported agents is maintained in the agent registry inside the project. Each entry binds an agent id (used on the command line) to the JSON config layout, file location, and capability flags that drive scope handling and validation. The --client / -c flag accepts a comma-separated list so several agents can be updated in one run Source: src/cli.ts:flag definitions Source: src/agents.ts:agent registry.

Agents that the repository explicitly recognizes include:

Beyond these, the registry contains entries for other popular coding agents and is the place to look for the full current list and any new additions Source: src/agents.ts:agent registry. The community has explicitly requested additions and wrappers — for example, remote MCP for Claude Desktop via mcp-remote is tracked in issue #58, and GitHub Copilot CLI global support in issue #4 — and these drive the shape of the registry over time Source: community issue #58 Source: community issue #4.

A practical consequence of the registry design is that adding a new agent is a code change in src/agents.ts rather than a user-facing configuration step; the release notes show this pattern (e.g. v1.10.3 introducing windsurf and its aliases codeium / cascade) Source: v1.10.3 release notes.

Configuration Model and File Locations

Each agent stores its MCP configuration in its own JSON file with its own top-level key. The CLI normalizes the user's input (--command, --args, --env, --header, --url, etc.) into an mcpServers entry like:

{
  "name": {
    "command": "/path/to/exe",
    "args": ["--flag", "value"],
    "env": { "KEY": "value" },
    "headers": { "Authorization": "Bearer ..." },
    "url": "https://example/mcp"     // for remote (HTTP) servers
  }
}

Some agents nest the servers under a different key (for example servers in VS Code); the agent entry handles that mapping. Per-agent "remote allowed" flags and validation live next to each registry entry so that the CLI can refuse to write remote URLs into agents that do not understand them — this is the mechanism behind the discussion in issue #58 about Claude Desktop currently not accepting remote MCP URLs directly Source: src/agents.ts:per-agent capabilities. Validation also rejects empty values such as --env "KEY=" and hints at shell-expansion failures when a ${VAR} placeholder has been eaten, which was a frequent source of silently broken configs before v1.9.1 Source: v1.9.1 release notes.

The CLI preserves paths that contain spaces, tildes, or absolute prefixes as a single executable token — this regression was fixed in v1.10.2 after users reported cases like /Applications/Hopper Disassembler.app/Contents/MacOS/HopperMCPServer being incorrectly split on whitespace Source: v1.10.2 release notes Source: community issue #29.

Scope, Selection, and Compatibility Notes

Installs are either global (written to the user's home directory config, affecting every project) or project (written to the working directory's config). The -g / --global flag forces global, while the absence of any scope flag triggers an interactive prompt in v1.13.0+ when every selected agent supports both scopes; -y keeps the run fully deterministic Source: v1.13.0 release notes Source: src/scope.ts:scope resolution. A single shared scope is used per run: if any selected agent is global-only, the entire run installs globally rather than mixing project and global writes Source: v1.13.0 release notes.

Two compatibility constraints recur in community reports:

1. Claude Desktop on Windows installed as MSIX uses non-standard paths that the CLI does not currently resolve, leading to mismatched reads/writes (issue #50).
2. OAuth / auth parameters for remote HTTP MCP servers (scopes, authProviderType, connection timeouts) are tracked as a feature request in issue #51 and are not yet part of the standard config shape emitted by the CLI.

For programmatic use, the exported detect returns the agents present on the current system based on existing config files and platform conventions, while upsert and remove perform the same writes the CLI does. The package is published via npm Trusted Publishing (OIDC) with provenance attestation, which is documented in docs/RELEASING.md Source: docs/RELEASING.md:publishing workflow Source: v1.10.0 release notes.

Related Pages

Related topics: Overview and Supported Agents, Programmatic API and Registry Configuration

CLI Commands Reference

add-mcp is a Node.js CLI that registers a Model Context Protocol (MCP) server into one or more AI agent configuration files. Its primary role is to detect which agents are installed on the current machine, prompt the user to choose a target, then write the server entry into the chosen file(s) at either global or project scope Source: src/index.ts:1-40.

The executable is published as the add-mcp npm binary. As of v1.10.0 the same surface is also exposed as a programmatic library (detect, upsert, remove) for callers that want to embed the logic without spawning the CLI Source: docs/RELEASING.md:1-20.

Command Surface

The CLI parses a single argv vector and dispatches into one of two top-level behaviors:

The parser is implemented around commander-style flag definitions in src/cli.ts, where every flag's short and long forms are declared alongside their default value and description Source: src/cli.ts:1-80. When no subcommand is supplied, the positional remainder is forwarded to the installer as the command value for the new MCP entry.

Agent Selection Flags

A run can be steered to one or more known agents via repeated -c <name> (client) flags. The set of recognized names — claude, claude-code, vscode, windsurf (aliases codeium, cascade), cursor, cline, zed, continue-dev, gemini-cli, github-copilot-cli, and others — is resolved in src/agents.ts, where each name maps to a detection routine and a JSON config path Source: src/agents.ts:20-140. When -c is omitted the CLI auto-detects installed agents and prompts the user to pick one interactively Source: src/index.ts:40-90.

Scope Flags

Two flags control whether the entry is written to a global config or a project-local one:

• -g, --global — force a global install for every selected agent.
• -y, --yes — accept defaults non-interactively; combined with -g this yields a deterministic global install.

A -p, --project flag is supported by agents that have both scopes. Since v1.13.0, when all selected agents support both scopes and neither -g nor -y is set, the CLI prompts for a single shared scope and writes it consistently across the run Source: CHANGELOG.md:1-30.

Server Definition Flags

The following flags shape the JSON entry written into the agent config:

Argument parsing enforces that the first positional token (the executable path or URL) is preserved verbatim — absolute, home-relative, dot-relative, and Windows drive paths are kept as a single command string rather than split on spaces, fixing the regression seen with "/Applications/My App/bin/server" in v1.10.2 Source: src/installer.ts:60-140.

Add Flow and Config Writing

Once target agents, scope, and server fields are resolved, the installer loads each target's existing JSON, locates the mcpServers object (or creates one), and writes the new entry. From v2.0.0 onward a re-install under an existing name replaces the entire prior entry instead of deep-merging fields; callers that need to preserve extra metadata must resend the full desired configuration Source: CHANGELOG.md:1-15.

The reader normalizes both the Claude-style mcpServers map and the VS Code-style servers map, and falls back to {} when the file is missing or empty Source: src/reader.ts:1-60. On Windows msix installs of Claude Desktop the resolved config path differs from the standard %APPDATA% location; this is a known gap tracked in issue #50.

`find` / `search` Subcommand

add-mcp find (alias search) lists servers from the configured registry. As of v1.14.0 the default registry endpoint is https://add-mcp.com/registry/api/v1/servers under the label "add-mcp registry"; the legacy mcp.agent-tooling.dev URL is still accepted and auto-migrated on first use Source: src/find.ts:1-120. From v1.13.2 the first run no longer prompts for a registry choice — it defaults to integrations.sh. v1.13.3 changed selection rows to display install targets (remote URLs or package names) instead of reverse-domain registry IDs.

After the user selects a row, the registry metadata is converted into the same flag set consumed by the add flow: named packageArguments become --flag value pairs, positional arguments keep their order, and ${VAR} placeholders in env, headers, and args are prompted for interactively unless -y is set Source: src/find.ts:120-220.

Removal and Library API

A remove subcommand (added per issue #16) deletes an entry by --name from the selected agents. The same operation is exposed as the remove() library function alongside detect() and upsert() for embedding Source: src/index.ts:90-140. These three functions are the supported integration points for tooling that wants the CLI's behavior without spawning it.

Quick Examples

# Add a local stdio server globally to Claude Desktop
add-mcp -g -c claude /usr/local/bin/my-mcp --name my-mcp

# Add a remote HTTP server with auth header to VS Code
add-mcp -c vscode https://api.example.com/mcp \
  --transport http \
  --header "Authorization: Bearer ${TOKEN}"

# Browse the registry and install interactively
add-mcp find

# Non-deterministic project install (prompts for scope)
add-mcp -c cursor ./bin/server

Common pitfalls surfaced by the community: paths containing spaces must be quoted (add-mcp "/Applications/Hopper Disassembler.app/..." — see issue #29), and --env "KEY=" is now rejected to avoid writing empty values that break servers at runtime Source: CHANGELOG.md:1-25.

Related Pages

Related topics: CLI Commands Reference, Architecture and Internals

Programmatic API and Registry Configuration

add-mcp exposes a stable library surface (detect, upsert, remove) that mirrors its CLI behaviour, while the find / search workflow is driven by an external registry that the project maintains through JSON files and a sync script. Together, these let other tools embed add-mcp as a configuration helper and curate which MCP servers users can discover.

Programmatic API (`src/lib.ts`)

Starting in v1.10.0, the package ships a programmatic API so that add-mcp can be consumed as a library in addition to being invoked as a CLI (Source: src/lib.ts:1-40). The surface is intentionally small and is organised around three operations that correspond to the lifecycle of an MCP server entry inside an agent configuration file.

• detect(agents) — enumerates which agent targets are available on the current machine and which scopes (global vs. project) they support. This is the same detection logic that the interactive agent picker uses.
• upsert(name, config, options) — writes a server entry under name into one or more agent configs. As of v2.0.0, re-installing under an existing name replaces the entire entry rather than deep-merging it, so callers must pass the full desired configuration (Source: src/lib.ts:80-140).
• remove(name, options) — deletes a named server entry from the selected agent configs. This addresses long-standing community demand for an uninstall path, surfaced in issue #16 (Source: src/lib.ts:140-200).

The three functions share option flags for agents, scope, dryRun, and configPath, so library callers can reproduce the CLI's behaviour (-g, -y, custom config location) without going through the CLI parser.

Registry Configuration

The find / search command downloads a list of known MCP servers from a remote registry URL. The default URL is https://add-mcp.com/registry/api/v1/servers under the label "add-mcp registry"; the previous https://mcp.agent-tooling.dev/... URL is still accepted and any saved config that references it is migrated automatically on the next run, with custom labels preserved and duplicates de-duplicated (Source: src/find.ts:30-90).

Two JSON files ship in the repository to curate and extend the upstream registry:

When find runs, it merges the upstream registry response with these local files. Custom labels are preserved across runs so users can pin a specific upstream snapshot if they need reproducibility (Source: registry.overlay.json:1-30).

Because the displayed install targets shifted away from reverse-domain registry IDs (v1.13.3) toward concrete commands/URLs, both files are expected to include a name, an install target (package name or remote URL), and optional packageArguments, env, and headers templates that match the flag set used on the CLI (Source: registry.json:1-40).

Registry Maintenance and Sync

The registry is not hand-edited from the upstream source — it is regenerated. scripts/sync-integrations-sh.mjs fetches the integrations.sh dataset, transforms it into the add-mcp registry shape, and writes the result into registry.json. This script is the reason that v1.13.1 expanded the available servers and that the README messaging was updated to point maintainers to integrations.sh for inclusion (Source: scripts/sync-integrations-sh.mjs:1-60).

A typical maintenance loop looks like:

1. Update or add a server on integrations.sh.
2. Run node scripts/sync-integrations-sh.mjs to regenerate registry.json.
3. Review the diff, optionally adding entries to registry.overlay.json for add-mcp-specific metadata (e.g., curated labels or default scopes).
4. Publish a release; saved user configs pointing at the old default URL are migrated lazily on the next find invocation.

This split — upstream data via the script, local curation via the overlay — keeps the curated list reproducible without forking the upstream dataset.

CLI vs. Library Boundaries

The CLI and the library share the same core functions, but they differ in ergonomics. The CLI owns interactive prompts (agent selection, scope selection when every selected agent supports both, per-flag ${VAR} template prompts) and stdout formatting for find results, while src/lib.ts returns structured values that callers can render themselves (Source: src/find.ts:90-160). Issue #57 ("Allow selecting scope (global or project) interactively") was addressed by adding a shared-scope prompt in v1.13.0, and that prompt logic is exposed through detect() rather than re-implemented by each consumer (Source: src/lib.ts:40-80).

Library consumers should therefore:

• Call detect() once to resolve agents and scope.
• Call upsert() / remove() with explicit agent and scope arguments when they want deterministic behaviour analogous to -y.
• Treat ${VAR} placeholders as opaque strings and either resolve them before calling the API or rely on the CLI to prompt for them.

This separation keeps the library safe to embed in non-interactive tooling (CI, installer scripts, editor extensions) while preserving the guided experience on the CLI.

Related Pages

Related topics: Overview and Supported Agents, CLI Commands Reference, Programmatic API and Registry Configuration

Architecture and Internals

add-mcp is a Node/TypeScript CLI and library that writes mcpServers entries into the configuration files of multiple AI coding agents. It follows a layered design: a CLI front-end (src/cli.ts), a public programmatic API (src/api.ts), a shared core that handles detection/upsert/remove operations, and a set of pluggable adapters for individual agents and configuration formats.

Module Layout and Process Flow

The runtime is split into three layers:

1. CLI layer — parses argv with commander in src/cli.ts, resolves the target agents, scope, and the server payload, then delegates to the core API.
2. Core API layer — src/api.ts exposes detect, upsert, and remove. As of v1.10.0 this surface is public, allowing the package to be imported as a library (Source: package.json:1-40).
3. Adapter layer — format adapters under src/formats/ serialize config files in JSON, TOML, or YAML. Agent adapters under src/agents.ts map logical agent ids to their config paths and scope rules.

User ──► CLI (cli.ts)
            │
            ▼
        Core API (api.ts): detect / upsert / remove
            │
            ├──► Scope resolver (scope.ts)
            ├──► Path resolver (paths.ts)
            ├──► Format adapter (formats/{json,toml,yaml}.ts)
            └──► Agent config file on disk

Configuration Format Adapters

Each agent stores its mcpServers block in a different file shape. A small dispatch layer normalizes them:

• src/formats/json.ts reads/writes JSON with stable key ordering so existing server entries are not reshuffled (Source: src/formats/json.ts:1-80).
• src/formats/toml.ts handles TOML used by some agents (Source: src/formats/toml.ts:1-60).
• src/formats/yaml.ts covers YAML-based configs (Source: src/formats/yaml.ts:1-60).
• src/formats/index.ts selects an adapter based on the agent's declared format and preserves comments where the underlying parser supports it (Source: src/formats/index.ts:1-40).

When re-installing under an existing name, v2.0.0 replaces the entire entry rather than deep-merging, eliminating stale-field leakage between runs (Source: CHANGELOG.md:1-20). This change is enforced inside the upsert path of src/api.ts.

Agent, Scope, and Path Resolution

Agent selection happens in two phases: detection of installed agents, then user confirmation (interactive) or CLI flags (-g, -y). The src/agents.ts registry declares, per agent, which config file path applies for global vs project scope, and which transport types (stdio, http, remote) are permitted (Source: src/agents.ts:1-120).

src/scope.ts enforces the "single shared scope per run" rule added in v1.13.0: if any selected agent is global-only, the whole run is forced to global scope instead of mixing project and global writes (Source: src/scope.ts:1-60). src/paths.ts expands ~, resolves Windows drive paths, and — as fixed in v1.10.2 — keeps paths containing spaces intact as the executable rather than splitting on whitespace (Source: src/paths.ts:1-80).

Registry and Interactive Flows

src/registry.ts fetches the find / search catalog. The default registry moved to https://add-mcp.com/registry/api/v1/servers in v1.14.0, with automatic migration of legacy mcp.agent-tooling.dev URLs in saved configs (Source: src/registry.ts:1-120). During interactive installs, registry entries that declare ${VAR} placeholders are surfaced through src/interactive.ts, which prompts for required env vars, headers, and packageArguments; optional keys that are skipped are omitted from the written config (Source: src/interactive.ts:1-100).

Community-Relevant Limitations

Several architectural constraints surface in tracked issues:

• Remote HTTP configurations lack first-class OAuth scope / authProviderType plumbing, which is a gap in the agent adapter layer rather than the core upsert (#51).
• Claude Desktop installed via Windows MSIX writes outside the resolved paths.ts locations; the path resolver must special-case the packaged install root (#50).
• --env "KEY=" with empty value was silently written and broke servers at runtime; the API layer now rejects it with a shell-expansion hint added in v1.9.1 (Source: src/api.ts:1-120).
• Wrapping remote MCPs in mcp-remote for Claude Desktop is not yet modeled in the agent registry (#58).

Doramagic Pitfall Log

Found 26 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
• Finding: Developers should check this installation risk before relying on the project: Add Packrift MCP server to registry
• User impact: Developers may fail before the first successful local run: Add Packrift MCP server to registry
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add Packrift MCP server to registry. Context: Observed when using docker
• Evidence: failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/35

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package
• User impact: Developers may fail before the first successful local run: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package. Context: Observed when using windows
• Evidence: failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/50

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.10.0
• User impact: Upgrade or migration may change expected behavior: v1.10.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.10.0. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.0

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.10.3
• User impact: Upgrade or migration may change expected behavior: v1.10.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.10.3. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.3

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.12.0
• User impact: Upgrade or migration may change expected behavior: v1.12.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.12.0. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.12.0

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.13.0
• User impact: Upgrade or migration may change expected behavior: v1.13.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.13.0. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.13.0

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.13.3
• User impact: Upgrade or migration may change expected behavior: v1.13.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.13.3. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.13.3

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.9.0
• User impact: Upgrade or migration may change expected behavior: v1.9.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.9.0. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.0

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.9.1
• User impact: Upgrade or migration may change expected behavior: v1.9.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.9.1. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v2.0.0
• User impact: Upgrade or migration may change expected behavior: v2.0.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v2.0.0

11. Installation risk: Installation risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/35

12. Installation risk: Installation risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/50

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using add-mcp with real data or production workflows.

• Bug: add-mcp list fails to display httpUrl for Gemini CLI servers - github / github_issue
• Support authentication parameters for remote HTTP configurations - github / github_issue
• Compatibility Issue: Does not work with Claude Desktop on Windows when i - github / github_issue
• Space character in server path breaks settings - github / github_issue
• Add Packrift MCP server to registry - github / github_issue
• v2.0.0 - github / github_release
• v1.14.0 - github / github_release
• v1.13.3 - github / github_release
• v1.13.2 - github / github_release
• v1.13.1 - github / github_release
• v1.13.0 - github / github_release
• v1.12.0 - github / github_release