# add-mcp > Add MCP servers to your favorite coding agents with a single command. # Introduction Source: https://add-mcp.com/docs `add-mcp` is an open-source CLI (and TypeScript SDK) that installs [Model Context Protocol](https://modelcontextprotocol.io) servers into the config files of your coding agents — Claude Code, Codex, Cursor, OpenCode, VS Code, Grok Build, and [16 more](/docs/agents) — with a single command. ```bash npx add-mcp https://mcp.context7.com/mcp ``` One command handles the whole flow: it detects which agents you use, asks which ones to install to (or takes flags for non-interactive use), and writes the right config shape to each agent's own file format — JSON, YAML, or TOML. :::note add-mcp is free and open source under the Apache-2.0 license. The code lives at [neon-solutions/add-mcp](https://github.com/neon-solutions/add-mcp). ::: ## What it does - **Install remote or local servers** — by URL (streamable HTTP or SSE), npm package, or arbitrary command. - **Find servers** — search the [add-mcp registry](/registry) right from the terminal with `add-mcp find` and install a match interactively. - **Manage installs** — `list`, `remove`, and `sync` server configs across all your agents. - **Programmatic use** — the [`add-mcp` npm package](https://www.npmjs.com/package/add-mcp) exposes an [SDK](/docs/sdk) so your own CLI or tool can install MCP servers for its users. ## Why not configure agents by hand? Every agent stores MCP servers in a different file, format, and shape: Cursor uses `.cursor/mcp.json`, Codex uses TOML at `.codex/config.toml`, Goose uses YAML, Claude Code splits project and global configs. Fields like timeouts, OAuth scopes, and tool auto-approval differ per client — some don't support them at all. add-mcp keeps one canonical server definition and maps it into each client's native schema, dropping unsupported fields with a warning instead of writing broken config. ## Next steps - [Quickstart](/docs/quickstart) — install your first MCP server. - [CLI reference](/docs/cli) — every command and flag. - [SDK](/docs/sdk) — programmatic use from your own tools. - [Registry](/docs/registry) — find servers and host your own registry. --- # Supported agents Source: https://add-mcp.com/docs/agents MCP servers can be installed to any of these agents. Project paths are relative to your working directory; agents without a project path are global-only. | Agent | `--agent` | Project path | Global path | | ---------------------- | -------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Antigravity | `antigravity` | — | `~/.gemini/config/mcp_config.json` (shared by Antigravity, Antigravity IDE, and Antigravity CLI) | | Cline VSCode Extension | `cline` | — | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | | Cline CLI | `cline-cli` | — | `~/.cline/data/settings/cline_mcp_settings.json` | | Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` | | Claude Desktop | `claude-desktop` | — | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` | | Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` | | fx | `fx` | — | `~/.fx/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` | `.mcp.json` (or existing `.github/mcp.json`) | `~/.copilot/mcp-config.json` | | Grok Build | `grok-build` | `.grok/config.toml` | `$GROK_HOME/config.toml` (defaults to `~/.grok/config.toml`) | | 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`) | | Kimi Code | `kimi-code` | `.kimi-code/mcp.json` | `$KIMI_CODE_HOME/mcp.json` (defaults to `~/.kimi-code/mcp.json`) | | Kiro CLI | `kiro-cli` | `.kiro/settings/mcp.json` | `~/.kiro/settings/mcp.json` (shared with the Kiro IDE) | | Mastra Code | `mastracode` | `.mastracode/mcp.json` | `~/.mastracode/mcp.json` | | MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) | | OpenCode | `opencode` | `opencode.jsonc` (or existing `opencode.json` / `.opencode/` config) | `~/.config/opencode/opencode.jsonc` (or existing `opencode.json`) | | Pi | `pi` | `.pi/mcp.json` | `$PI_CODING_AGENT_DIR/mcp.json` (defaults to `~/.pi/agent/mcp.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/settings.json` | ## Aliases | Alias | Resolves to | | -------------------- | ------------ | | `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` | ## Troubleshooting Some agents and editors, like Claude Code, require a restart to load a new MCP server. Others, like Cursor, require you to navigate to the MCP settings page and toggle the new server as enabled. 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. Its MCP config is also validated as a whole: if another entry in the file is invalid, Kimi Code disables every MCP server, including a newly added one. Mastra Code also reads project `.mcp.json`. add-mcp writes `.mastracode/mcp.json` (and `~/.mastracode/mcp.json` globally) so a mixed Claude + Mastra install does not share that file. Pi has no built-in MCP. add-mcp writes the Pi-owned files [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) reads. Install that extension with `pi install npm:pi-mcp-adapter`. A running Pi session picks the change up after `/reload`. 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`. OpenCode keeps the shape already in the file: `mcp.` on a V1 or empty config, `mcp.servers.` 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. 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`. --- # Overview Source: https://add-mcp.com/docs/cli The implicit default command installs a server from a URL, package name, or command. Everything else is a named subcommand: | Command | Description | | -------------------------------- | ------------------------------------------------------------ | | [`add-mcp `](/docs/cli/add) | Install an MCP server by URL, npm package, or command | | [`find`](/docs/cli/find) | Search MCP registries and install a selected match | | [`search`](/docs/cli/find) | Alias for `find` | | [`list`](/docs/cli/list) | List installed MCP servers across detected agents | | [`remove`](/docs/cli/remove) | Remove an MCP server from agent configurations | | [`sync`](/docs/cli/sync) | Synchronize server names and installations across agents | | [`unify`](/docs/cli/sync) | Alias for `sync` | | `list-agents` | List all supported coding agents with scope (project/global) | ## Shared flags These flags work on every install-capable command: | Flag | Description | | --------------------- | ------------------------------------------------------------------------ | | `-g, --global` | Install to user directory instead of project | | `-a, --agent ` | Target specific agents (e.g. `cursor`, `claude-code`). Repeatable. | | `-y, --yes` | Skip all confirmation prompts | | `--all` | Install to all agents | | `--gitignore` | Add generated config files to `.gitignore` | ## Smart detection The CLI automatically detects agents based on your environment: - **Project mode (default)** — detects project-level config files (`.cursor/`, `.vscode/`, `.mcp.json`, ...) and preselects the detected agents. - **Global mode (`-g`)** — detects all globally-installed agents (including Claude Desktop, Codex, Zed) and preselects them. - **No agents detected** — interactive mode defaults to your last selection; with `--yes`, installs to all project-capable agents (project mode) or all global-capable agents (global mode). --- # add Source: https://add-mcp.com/docs/cli/add The default command. Pass a remote URL, an npm package name, or a full command: ```bash npx add-mcp [options] ``` ## Examples ```bash # Remote MCP server (streamable HTTP, the default transport) npx add-mcp https://mcp.example.com/mcp # Remote MCP server over SSE npx add-mcp https://mcp.example.com/sse --transport sse # Remote server with an auth header npx add-mcp https://mcp.example.com/mcp --header 'Authorization: Bearer ${TOKEN}' # Remote server; fx reads the bearer token from this env var npx add-mcp https://mcp.example.com/mcp --bearer-token-env NEON_API_KEY # Remote server with a request timeout and OAuth scopes (capability-gated) npx add-mcp https://mcp.example.com/mcp --timeout 30000 --scopes "read,write" # npm package (runs via npx) npx add-mcp @modelcontextprotocol/server-postgres # Full command with arguments npx add-mcp "npx -y @org/mcp-server --flag value" # Node.js script npx add-mcp "node /path/to/server.js --port 3000" # Local stdio server with environment variables (repeatable) npx add-mcp @modelcontextprotocol/server-filesystem --env "API_KEY=secret" --env "DATABASE_URL=postgres://localhost/app" # Auto-approve all tools for agents that support it (Codex, Claude Code) npx add-mcp "executor mcp" --name executor -a codex -a claude-code --auto-approve # Non-interactive install to the global Claude Code config npx add-mcp https://mcp.example.com/mcp -g -a claude-code -y ``` ## Options | Option | Description | | --------------------------- | ------------------------------------------------------------------------ | | `-g, --global` | Install to user directory instead of project | | `-a, --agent ` | Target specific agents (e.g. `cursor`, `claude-code`). Repeatable. | | `-t, --transport ` | Transport type for remote servers: `http` (default), `sse` | | `--type ` | Alias for `--transport` | | `-h, --header
` | HTTP header for remote servers (repeatable, `Key: Value`) | | `--bearer-token-env ` | Env var whose value fx sends as a bearer token (capability-gated) | | `--env ` | Env var for local stdio servers (repeatable, `KEY=VALUE`) | | `--args ` | Arguments for local stdio servers | | `--timeout ` | Request timeout (ms) for remote servers (capability-gated) | | `--scopes ` | OAuth scopes for remote servers, comma-separated (capability-gated) | | `--oauth-scopes ` | Alias for `--scopes` | | `--auto-approve` | Auto-approve MCP tool calls for supported agents (Codex, Claude Code) | | `--approve-tool ` | Tool to auto-approve with `--auto-approve` (repeatable; defaults to all) | | `-n, --name ` | Server name (auto-inferred if not provided) | | `-y, --yes` | Skip all confirmation prompts | | `--all` | Install to all agents | | `--gitignore` | Add generated config files to `.gitignore` | ## Transports | Transport | Flag | Description | | --------- | ------------------ | ----------------------------------------------------- | | **HTTP** | `--transport http` | Streamable HTTP (default) | | **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) | Local servers (npm packages, commands) always use **stdio** transport. Most agents (Cursor, OpenCode, ...) don't need the transport type spelled out; add-mcp sets it where required. ## Capability-gated fields Not every MCP client understands every field. add-mcp keeps one canonical server config; each agent declares which optional fields it supports and maps them into its native shape: | Field | Flag | Supported by | Mapped to | | ------------------ | ----------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Timeout | `--timeout` | Claude Code, Gemini CLI, Grok Build, Kilo Code, Kimi Code, Kiro CLI, Pi | `timeout` (milliseconds); Grok Build `tool_timeout_sec` (seconds), Kimi Code `toolTimeoutMs`, Pi `requestTimeoutMs` | | OAuth scopes | `--scopes` | Cursor, Gemini CLI, Mastra Code | Cursor `auth.scopes`, Gemini and Mastra Code `oauth.scopes` | | Bearer token env | `--bearer-token-env` | fx | `bearer_token_env` | | Tool auto-approval | `--auto-approve` / `--approve-tool` | Codex, Claude Code | Codex approval modes; Claude Code permission allow rules | When a targeted agent doesn't support a field, add-mcp drops it from that agent's config and prints a warning — other agents still receive it. `--timeout`, `--scopes`, and `--bearer-token-env` apply to remote servers only. When `--bearer-token-env` and `--header Authorization` are both set, fx omits the Authorization header and writes `bearer_token_env`; other agents keep the header. ## Auto-approving tool calls `--auto-approve` preconfigures agent-level approval so the agent doesn't prompt before each MCP tool call. Use `--approve-tool ` (repeatable) to approve only specific tools; without it, all tools are approved. - **Codex** — writes approval modes into `config.toml`: per-tool `tools..approval_mode = "approve"`, or `default_tools_approval_mode = "approve"` for all tools. - **Claude Code** — writes permission allow rules to a separate settings file (`.claude/settings.local.json` for project installs, `~/.claude/settings.json` for global), e.g. `mcp____`. The MCP server entry itself stays clean. :::warning Claude Code's all-tools rule (`mcp__`) follows the documented format, but a known Claude Code bug ([#34739](https://github.com/anthropics/claude-code/issues/34739)) can still prompt for non-fully-qualified MCP rules. Listing tools explicitly with `--approve-tool` is the most reliable path there. ::: --- # find / search Source: https://add-mcp.com/docs/cli/find Search configured MCP registries by keyword and install a result interactively. `search` is an alias for `find`. ```bash npx add-mcp find [options] ``` ## Examples ```bash # Search for servers by keyword and choose one interactively npx add-mcp find vercel # Browse servers without a keyword npx add-mcp find # Use the search alias (same as find) npx add-mcp search notion # Install a found server globally to a specific agent without prompts npx add-mcp find neon -a claude-code -g -y # Install to all agents and add generated project configs to .gitignore npx add-mcp find github --all --gitignore ``` ## Options | Option | Description | | ----------------------- | ------------------------------------------------------------------------ | | `-g, --global` | Install to user directory instead of project | | `-a, --agent ` | Target specific agents (e.g. `cursor`, `claude-code`). Repeatable. | | `-n, --name ` | Server name override (defaults to the selected catalog entry name) | | `-y, --yes` | Skip confirmation prompts | | `--auto-approve` | Auto-approve MCP tool calls for supported agents (Codex, Claude Code) | | `--approve-tool ` | Tool to auto-approve with `--auto-approve` (repeatable; defaults to all) | | `--all` | Install to all agents | | `--gitignore` | Add generated config files to `.gitignore` | ## Transport selection Transport is inferred from registry metadata. The CLI prefers HTTP remotes when available and only falls back to SSE when HTTP isn't available for the selected install context. 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. If a selected remote server defines URL variables or header inputs: - required values must be provided, - optional values can be skipped with Enter, - with `-y`, placeholders are inserted (for example ``). ## Registries The first `find`/`search` run saves the default [add-mcp registry](/docs/registry) to `~/.config/add-mcp/config.json` and reuses it on every subsequent search. See the [registry docs](/docs/registry) for editing, adding, or hosting registries. --- # list Source: https://add-mcp.com/docs/cli/list ```bash npx add-mcp list [options] ``` ## Examples ```bash # List servers for all detected agents in the project npx add-mcp list # List global server configs npx add-mcp list -g # List servers for a specific agent (shown even if not detected) npx add-mcp list -a cursor ``` ## Options | Option | Description | | --------------------- | -------------------------------------- | | `-g, --global` | List global configs instead of project | | `-a, --agent ` | Filter to specific agent(s) | ## Related: list-agents `list-agents` prints all supported coding agents with their supported scopes (project/global): ```bash npx add-mcp list-agents ``` --- # remove Source: https://add-mcp.com/docs/cli/remove Remove a server by name, URL, or package name: ```bash npx add-mcp remove [options] ``` ## Examples ```bash # Remove by server name (interactive selection by default) npx add-mcp remove neon # Remove all matches without prompting npx add-mcp remove neon -y # Remove by URL npx add-mcp remove https://mcp.neon.tech/mcp -y # Remove from global configs for a specific agent npx add-mcp remove neon -g -a cursor -y ``` ## Options | Option | Description | | --------------------- | ------------------------------------ | | `-g, --global` | Remove from global configs | | `-a, --agent ` | Filter to specific agent(s) | | `-y, --yes` | Remove all matches without prompting | --- # sync Source: https://add-mcp.com/docs/cli/sync 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. `unify` is an alias for `sync`. ```bash npx add-mcp sync [options] ``` ## Examples ```bash # Sync project-level configs (interactive confirmation) npx add-mcp sync # Sync without prompting npx add-mcp sync -y # Sync global configs npx add-mcp sync -g -y ``` ## Options | Option | Description | | -------------- | -------------------------------------- | | `-g, --global` | Sync global configs instead of project | | `-y, --yes` | Skip confirmation prompts | --- # Quickstart Source: https://add-mcp.com/docs/quickstart add-mcp runs with `npx` (or `bunx`) — there's nothing to install first. Node.js 18 or newer is required. ## Install a remote MCP server Pass a server URL and add-mcp does the rest: ```bash npx add-mcp https://mcp.context7.com/mcp ``` The CLI detects the agents configured in your project (`.cursor/`, `.vscode/`, `.mcp.json`, ...), preselects them, and lets you confirm or adjust the selection. It then writes the server into each agent's own config file and format. ## Install an npm package (stdio server) Local stdio servers work the same way — pass the package name: ```bash npx add-mcp @modelcontextprotocol/server-postgres ``` The server is registered to run via `npx` in each agent's config. ## Find a server by keyword Don't know the URL? Search the [registry](/registry) from the terminal: ```bash npx add-mcp find neon ``` Pick a result, and add-mcp installs it with the right transport (it prefers streamable HTTP remotes and falls back to packages) — including prompting for any required environment variables or headers. ## Common variations ```bash # Install globally (user-level config) instead of the project npx add-mcp https://mcp.example.com/mcp -g # Target specific agents npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code # Non-interactive (CI-friendly): no prompts npx add-mcp https://mcp.example.com/mcp -y # With an auth header npx add-mcp https://mcp.example.com/mcp --header 'Authorization: Bearer ${TOKEN}' # With env vars for a stdio server npx add-mcp @modelcontextprotocol/server-filesystem --env "API_KEY=secret" ``` :::tip Use single quotes around values with `${VAR}` placeholders so your shell doesn't expand them. Interactive installs prompt for each placeholder value. ::: ## Project vs. global scope | Scope | Flag | Written to | Use case | | ----------- | --------- | ------------------------- | ---------------------------------------------- | | **Project** | (default) | `.cursor/mcp.json`, etc. | Committed with your project, shared with team | | **Global** | `-g` | `~/.cursor/mcp.json` etc. | Available across all projects | When every selected agent supports both scopes, interactive mode asks which one you want. `-g` always forces global, and `-y` stays deterministic. ## Next steps - [CLI reference](/docs/cli) — all commands: `add`, `find`, `list`, `remove`, `sync`. - [Supported agents](/docs/agents) — the full agent table with config paths. - [SDK](/docs/sdk) — install MCP servers from your own tool. --- # Registry Source: https://add-mcp.com/docs/registry The [add-mcp registry](/registry) is a searchable catalog of MCP servers, generated from [integrations.sh](https://integrations.sh) data. Browse it on the web at [add-mcp.com/registry](/registry), or search it from the terminal: ```bash npx add-mcp find neon ``` ## Built-in registries | Registry | Base URL | Description | | ------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **add-mcp registry** | `https://add-mcp.com/registry/api/v1/servers` | MCP servers discovered by integrations.sh, exposed through a registry-compatible API. The default. | | **Official Anthropic registry** | `https://registry.modelcontextprotocol.io/v0.1/servers` | The community-driven MCP server registry maintained by Anthropic — the broadest catalog. | The first `find`/`search` run automatically saves the default registry to `~/.config/add-mcp/config.json` (respects `XDG_CONFIG_HOME`) and reuses it on every subsequent search. :::note The add-mcp registry previously lived at `mcp.agent-tooling.dev`. That URL keeps working — existing configs are not broken — but new installs use `add-mcp.com/registry` and the CLI migrates saved configs automatically. ::: ## Editing or removing registries Registry selections are stored under the `findRegistries` key. Edit the file directly to replace, add, remove, or reorder registries: ```json title="~/.config/add-mcp/config.json" { "version": 1, "findRegistries": [ { "url": "https://add-mcp.com/registry/api/v1/servers", "label": "add-mcp registry" }, { "url": "https://registry.modelcontextprotocol.io/v0.1/servers", "label": "Official Anthropic registry" } ] } ``` To reset to the default registry, remove the `findRegistries` key or delete the config file. ## Missing a server? The registry is generated from [integrations.sh](https://integrations.sh). To be listed, add your MCP server there. Package-only servers, and remotes integrations.sh dropped that we still want in `find`, can be contributed to add-mcp's `registry.overlay.json` on [GitHub](https://github.com/neon-solutions/add-mcp). ## Adding a custom registry Any server that implements the registry API can be used. The CLI sends a `GET` request to the configured `url` with these query parameters: | Parameter | Value | | --------- | -------------------------------------- | | `search` | The user's search keyword (lowercased) | | `version` | `latest` | | `limit` | `100` | | `source` | `cli` | The endpoint must return JSON in this shape: ```json { "servers": [ { "server": { "name": "example-server", "description": "An example MCP server", "version": "1.0.0", "remotes": [ { "type": "streamable-http", "url": "https://mcp.example.com/mcp" } ] } } ] } ``` Append an entry to `findRegistries` in `~/.config/add-mcp/config.json`: ```json { "url": "https://my-registry.example.com/api/v1/servers", "label": "My custom registry" } ``` ## Registry API The add-mcp registry itself exposes a read-only JSON API with search and cursor pagination: ```bash curl "https://add-mcp.com/registry/api/v1/servers?search=neon&limit=10" ``` The full OpenAPI spec is served at [`/registry/api/openapi.json`](/registry/api/openapi.json). The registry server is open source and self-hostable: [agent-tooling/mcp-registry](https://github.com/agent-tooling/mcp-registry). ## Search analytics The hosted add-mcp registry records search terms from the website and registry API. The add-mcp CLI identifies its searches separately, so usage can be analyzed by website, CLI, or generic API traffic. The public all-time and weekly totals, trending terms, rankings, and per-server search counts combine every source. --- # Programmatic use Source: https://add-mcp.com/docs/sdk The `add-mcp` npm package doubles as a TypeScript SDK. If you're building a CLI or developer tool that should set up an MCP server for its users ("add our MCP server to Cursor with one command"), the SDK gives you the same battle-tested config writing the CLI uses — every agent, every format, capability gating included. ## Install ```package-install add-mcp ``` ## Add a server to an agent ```ts import { upsertServer } from "add-mcp"; // Remote server → project-level Cursor config (.cursor/mcp.json) const result = upsertServer( "cursor", "context7", { type: "http", url: "https://mcp.context7.com/mcp" }, { local: true }, ); if (!result.success) { console.error(result.error); } console.log(`written to ${result.path}`); ``` Stdio servers work the same way: ```ts import { upsertServer } from "add-mcp"; // npm package → global Claude Code config upsertServer("claude-code", "postgres", { command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], }); ``` `upsertServer` and `removeServer` return `{ success, path, error? }` rather than throwing, so a failed write in one agent never crashes your tool. ## Detect the user's agents ```ts import { detectProjectAgents, detectGlobalAgents } from "add-mcp"; const project = detectProjectAgents("/path/to/project"); // sync const global = await detectGlobalAgents(); // async ``` Combine detection with `upsertServer` to offer a one-command install across everything the user actually has: ```ts import { detectProjectAgents, upsertServer } from "add-mcp"; for (const agent of detectProjectAgents(process.cwd())) { upsertServer( agent, "my-server", { type: "http", url: "https://mcp.example.com/mcp" }, { local: true, cwd: process.cwd() }, ); } ``` ## List and remove ```ts import { listInstalledServers, removeServer } from "add-mcp"; const projectServers = await listInstalledServers({ cwd: "/path/to/project" }); const globalServers = await listInstalledServers({ global: true }); removeServer("claude-code", "example", { local: true, cwd: "/path/to/project", }); ``` ## Next steps - [API reference](/docs/sdk/reference) — every exported function and type. --- # API reference Source: https://add-mcp.com/docs/sdk/reference All exports come from the package root: ```ts import { upsertServer, removeServer, listInstalledServers, detectProjectAgents, detectGlobalAgents, getAgentTypes, agents, } from "add-mcp"; ``` ## upsertServer Adds or updates an MCP server in an agent's config file. Creates the config file (and parent directories) when missing. ```ts function upsertServer( agentType: AgentInput, serverName: string, serverConfig: McpServerConfig, options?: InstallOptions, ): InstallResult; ``` | Parameter | Type | Description | | -------------- | ----------------- | -------------------------------------------------------------------------------------- | | `agentType` | `AgentInput` | Agent identifier, e.g. `"cursor"`, `"claude-code"`. Validated at runtime. | | `serverName` | `string` | Key the server is stored under in the agent config. | | `serverConfig` | `McpServerConfig` | Canonical server definition (see below). | | `options` | `InstallOptions` | `{ local?: boolean; cwd?: string }` — project-level install and its working directory. | Returns [`InstallResult`](#installresult). Never throws — errors are reported via `result.error`. ## removeServer Removes a server entry from an agent's config file. Succeeds (with `removed: false`) when the config or entry doesn't exist. ```ts function removeServer( agentType: AgentInput, serverName: string, options?: InstallOptions, ): RemoveServerResult; ``` Returns `{ success: boolean; path: string; removed: boolean; error?: string }`. ## listInstalledServers Gathers installed servers across detected (or explicitly specified) agents. ```ts function listInstalledServers(options: { global?: boolean; agents?: AgentType[]; cwd?: string; }): Promise; ``` When `agents` is provided, those agents are included even if not detected (with `detected: false`). A detected agent whose config cannot be read is still returned, with `servers: []` and `error` set to the failure message. ## detectProjectAgents Detects agents with project-level config files in a directory (synchronous). ```ts function detectProjectAgents(cwd?: string): AgentType[]; ``` ## detectGlobalAgents Detects globally-installed agents by their global config paths (asynchronous). ```ts function detectGlobalAgents(): Promise; ``` ## getAgentTypes Returns all supported agent identifiers. ```ts function getAgentTypes(): AgentType[]; ``` ## agents The full agent capability map — `Record` with each agent's display name, config paths, file format, supported transports, and supported optional fields. ## Types ### McpServerConfig The canonical server definition. add-mcp maps it into each client's native schema and strips capability-gated fields the target agent doesn't support. ```ts interface McpServerConfig { // Remote servers type?: "http" | "sse"; url?: string; headers?: Record; // Local stdio servers command?: string; args?: string[]; env?: Record; // Capability-gated optional fields timeout?: number; // milliseconds; Claude Code, Gemini CLI, Grok Build, Kilo Code, Kimi Code, Kiro CLI oauthScopes?: string[]; // Cursor, Gemini CLI autoApproveTools?: string[]; // Codex, Claude Code; [] = all tools bearerTokenEnv?: string; // fx writes bearer_token_env } ``` ### InstallOptions ```ts interface InstallOptions { /** Install to local (project-level) config instead of global */ local?: boolean; /** Current working directory for local installs */ cwd?: string; } ``` ### InstallResult ```ts interface InstallResult { success: boolean; path: string; error?: string; /** Optional fields dropped because the agent doesn't support them */ droppedFields?: OptionalField[]; /** Additional files written beyond the main config */ extraPaths?: string[]; } ``` ### AgentType ```ts type AgentType = | "antigravity" | "cline" | "cline-cli" | "claude-code" | "claude-desktop" | "codex" | "cursor" | "fx" | "gemini-cli" | "goose" | "github-copilot-cli" | "grok-build" | "kilo-code" | "kimi-code" | "kiro-cli" | "mastracode" | "mcporter" | "opencode" | "pi" | "vscode" | "windsurf" | "zed"; ``` `AgentInput` is `AgentType | (string & {})` — it keeps autocomplete on the known literals while accepting arbitrary strings that are validated at runtime. ### AgentServers / InstalledServer Returned by `listInstalledServers`: ```ts interface AgentServers { agentType: AgentType; displayName: string; detected: boolean; scope: "local" | "global"; configPath: string; servers: InstalledServer[]; /** Set when this agent's config could not be read */ error?: string; } interface InstalledServer { serverName: string; config: Record; /** URL for remote servers, package/command string for stdio servers */ identity: string; agentType: AgentType; scope: "local" | "global"; configPath: string; /** Key in the config file this server was read from. `""` means the file root (a Copilot CLI bare name map). */ configKey: string; } ```