Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neon-solutions/add-mcp/llms.txt

Use this file to discover all available pages before exploring further.

The add-mcp package ships a fully typed programmatic API that lets you integrate MCP server management directly into your own CLI tools, setup scripts, or Node.js applications — no shell invocation required. Every public function is exported from the add-mcp package entry point and mirrors the behaviour of the CLI commands.

​
Installation

npm install add-mcp

​
Public API Reference

​
upsertServer

Creates or updates an MCP server entry in an agent’s configuration file. If the server already exists it is overwritten with the new config; otherwise it is created. The function is synchronous and never throws — errors are returned in the result object. 
function upsertServer(
  agentType: AgentInput,
  serverName: string,
  serverConfig: McpServerConfig,
  options?: InstallOptions
): InstallResult
​
agentType
AgentInput
required
The target agent identifier, e.g. 'cursor', 'claude-code', 'vscode'. Accepts any AgentType literal or an arbitrary string that is validated at runtime with a descriptive error message. See AgentType for the full list.
​
serverName
string
required
The key under which the server is stored in the config file (e.g. 'context7', 'postgres'). Must be unique within the agent’s MCP servers list.
​
serverConfig
McpServerConfig
required
The server configuration object. Use url for remote servers and command / args for local stdio servers. See McpServerConfig for the full shape.
​
options
InstallOptions
Optional install options.
Returns InstallResult:
​
success
boolean
true if the server was written successfully, false on error.
​
path
string
Absolute path to the config file that was written (or attempted).
​
error
string
Human-readable error message. Only present when success is false.
upsertServer and removeServer never throw exceptions. Always inspect the success field before assuming the operation succeeded.

​
removeServer

Removes an MCP server entry from an agent’s configuration file. If the file does not exist, or the server is not present in the config, the function still returns success: true with removed: false — a missing server is not treated as an error. 
function removeServer(
  agentType: AgentInput,
  serverName: string,
  options?: InstallOptions
): RemoveServerResult
​
agentType
AgentInput
required
The target agent identifier.
​
serverName
string
required
The server key to remove.
​
options
InstallOptions
Same local / cwd options as upsertServer.
Returns RemoveServerResult:
​
success
boolean
true unless an unexpected filesystem error occurred.
​
path
string
Absolute path to the config file that was examined.
​
removed
boolean
true if the server existed and was removed. false if the config file did not exist or the server was not present (not an error condition).
​
error
string
Error message, only present when success is false.

​
listInstalledServers

Gathers installed MCP servers across all detected or explicitly specified agents. Detects project-level agents by scanning for config files in cwd, or globally-installed agents by checking known install paths and binaries. 
async function listInstalledServers(options: {
  global?: boolean;
  agents?: AgentType[];
  cwd?: string;
}): Promise<AgentServers[]>
​
options.global
boolean
When true, lists servers from global user configs instead of project-level configs.
​
options.agents
AgentType[]
Explicit list of agents to include. Agents in this list are always returned even if not detected; non-detected agents will have an empty servers array and detected: false.
​
options.cwd
string
Working directory for project-level detection. Defaults to process.cwd().
Returns Promise<AgentServers[]>:
​
agentType
AgentType
The agent identifier string.
​
displayName
string
Human-readable agent name, e.g. 'Cursor', 'Claude Code'.
​
detected
boolean
Whether the agent was detected in the environment (config file or binary present).
​
scope
"local" | "global"
Whether the result reflects project-level or global config.
​
configPath
string
Absolute path to the agent’s config file.
​
servers
InstalledServer[]
Array of servers found in this agent’s config. Each entry includes serverName, config, identity, agentType, scope, and configPath.

​
detectProjectAgents

Synchronously returns the list of agent types that have project-level config files in the given directory. 
function detectProjectAgents(cwd?: string): AgentType[]
​
cwd
string
Directory to scan for project-level config files. Defaults to process.cwd().
Returns AgentType[] — agent types whose config files (e.g. .cursor/mcp.json, .mcp.json) exist under cwd.

​
detectGlobalAgents

Asynchronously returns the list of agent types that are installed globally on the machine. Detection checks for known config directories and binary presence. 
async function detectGlobalAgents(): Promise<AgentType[]>
Returns Promise<AgentType[]> — agent types detected globally.

​
agents

An object mapping every AgentType string to its full AgentConfig descriptor — display name, config file paths, supported transports, config format, and more. 
const agents: Record<AgentType, AgentConfig>

​
getAgentTypes

Returns all supported agent type strings as an array. Useful for building selectors or validation lists. 
function getAgentTypes(): AgentType[]
Returns AgentType[] — all 15 supported agent identifiers.

​
Type Reference

​
AgentType

type AgentType =
  | 'antigravity'
  | 'cline'
  | 'cline-cli'
  | 'claude-code'
  | 'claude-desktop'
  | 'codex'
  | 'cursor'
  | 'gemini-cli'
  | 'goose'
  | 'github-copilot-cli'
  | 'mcporter'
  | 'opencode'
  | 'vscode'
  | 'windsurf'
  | 'zed';
Use the AgentInput type (not AgentType) when accepting agent names from user input — it widens to string & {}, preserving autocomplete on valid literals while still accepting arbitrary strings that are validated at runtime with a helpful error message.

​
McpServerConfig

interface McpServerConfig {
  // Remote servers (HTTP / SSE)
  type?: 'sse' | 'http';
  url?: string;
  headers?: Record<string, string>;

  // Local stdio servers
  command?: string;
  args?: string[];
  env?: Record<string, string>;
}

​
InstallOptions

interface InstallOptions {
  local?: boolean; // write to project-level config
  cwd?: string;    // working directory for local installs
}

​
InstallResult

interface InstallResult {
  success: boolean;
  path: string;    // absolute path to the config file
  error?: string;  // present only on failure
}

​
RemoveServerResult

interface RemoveServerResult {
  success: boolean;
  path: string;      // absolute path to the config file examined
  removed: boolean;  // true if the server existed and was removed
  error?: string;    // present only when success is false
}

​
Code Examples

​
Install a remote HTTP server

import { upsertServer } from 'add-mcp';

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

if (!result.success) {
  console.error('Install failed:', result.error);
} else {
  console.log('Written to:', result.path);
  // Written to: /your/project/.cursor/mcp.json
}

​
Install a stdio (npm package) server

import { upsertServer } from 'add-mcp';

upsertServer('claude-code', 'postgres', {
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-postgres'],
  env: { DATABASE_URL: 'postgres://localhost/mydb' }
});

​
Install a remote server with an auth header

import { upsertServer } from 'add-mcp';

upsertServer(
  'claude-code',
  'neon',
  {
    type: 'http',
    url: 'https://mcp.neon.tech/mcp',
    headers: { Authorization: 'Bearer my-token' }
  },
  { local: true }
);

​
Remove a server

import { removeServer } from 'add-mcp';

const result = removeServer('cursor', 'context7', { local: true });

if (result.removed) {
  console.log('Server removed from', result.path);
} else {
  console.log('Server was not present — nothing to remove.');
}

​
List all installed servers across agents

import { listInstalledServers } from 'add-mcp';

const agentServersList = await listInstalledServers({ cwd: '/path/to/project' });

for (const agentServers of agentServersList) {
  const names = agentServers.servers.map(s => s.serverName);
  console.log(agentServers.displayName, names);
}

import { listInstalledServers } from 'add-mcp';

// List servers from global user configs
const global = await listInstalledServers({ global: true });
for (const agentServers of global) {
  console.log(agentServers.displayName, agentServers.servers.length, 'server(s)');
}

​
Detect agents

import { detectProjectAgents, detectGlobalAgents } from 'add-mcp';

// Synchronous — checks for project config files
const projectAgents = detectProjectAgents('/path/to/project');
console.log('Project agents:', projectAgents);
// e.g. ['cursor', 'claude-code']

// Asynchronous — checks global install paths and binaries
const globalAgents = await detectGlobalAgents();
console.log('Global agents:', globalAgents);
// e.g. ['cursor', 'claude-desktop', 'vscode']

​
Enumerate all agent types

import { getAgentTypes, agents } from 'add-mcp';

for (const type of getAgentTypes()) {
  const agent = agents[type];
  console.log(type, '->', agent.displayName, agent.configPath);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us