Using the add-mcp Programmatic API in TypeScript and JS

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

pnpm add add-mcp

yarn add 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

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.

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.

McpServerConfig

required

The server configuration object. Use url for remote servers and command / args for local stdio servers. See McpServerConfig for the full shape.

InstallOptions

Optional install options.

Show InstallOptions fields

boolean

When true, writes to the project-level config file (e.g. .cursor/mcp.json) instead of the global user config. Defaults to false.

string

Working directory used to resolve the project-level config path. Defaults to process.cwd().

Returns InstallResult:

boolean

true if the server was written successfully, false on error.

string

Absolute path to the config file that was written (or attempted).

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

AgentInput

required

The target agent identifier.

string

required

The server key to remove.

InstallOptions

Same local / cwd options as upsertServer.

Returns RemoveServerResult:

boolean

true unless an unexpected filesystem error occurred.

string

Absolute path to the config file that was examined.

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).

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[]>

boolean

When true, lists servers from global user configs instead of project-level configs.

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.

string

Working directory for project-level detection. Defaults to process.cwd().

Returns Promise<AgentServers[]>:

AgentType

The agent identifier string.

string

Human-readable agent name, e.g. 'Cursor', 'Claude Code'.

boolean

Whether the agent was detected in the environment (config file or binary present).

"local" | "global"

Whether the result reflects project-level or global config.

string

Absolute path to the agent’s config file.

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[]

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
}

const { upsertServer } = require('add-mcp');

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

console.log(result);
// { success: true, path: '.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)');
}

import { listInstalledServers } from 'add-mcp';

// Inspect only Cursor and Claude Code
const filtered = await listInstalledServers({
  agents: ['cursor', 'claude-code'],
  cwd: process.cwd(),
});

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);
}

Get Started

Commands

Concepts

Registries

Guides

Using the add-mcp Programmatic API in TypeScript and JS

Installation

Public API Reference

`upsertServer`

`removeServer`

`listInstalledServers`

`detectProjectAgents`

`detectGlobalAgents`

`agents`

`getAgentTypes`

Type Reference

`AgentType`

`McpServerConfig`

`InstallOptions`

`InstallResult`

`RemoveServerResult`

Code Examples

Install a remote HTTP server

Install a stdio (npm package) server

Install a remote server with an auth header

Remove a server

List all installed servers across agents

Detect agents

Enumerate all agent types

​Installation

​Public API Reference

​upsertServer

​removeServer

​listInstalledServers

​detectProjectAgents

​detectGlobalAgents

​agents

​getAgentTypes

​Type Reference

​AgentType

​McpServerConfig

​InstallOptions

​InstallResult

​RemoveServerResult

​Code Examples

​Install a remote HTTP server

​Install a stdio (npm package) server

​Install a remote server with an auth header

​Remove a server

​List all installed servers across agents

​Detect agents

​Enumerate all agent types

Installation

Public API Reference

`upsertServer`

`removeServer`

`listInstalledServers`

`detectProjectAgents`

`detectGlobalAgents`

`agents`

`getAgentTypes`

Type Reference

`AgentType`

`McpServerConfig`

`InstallOptions`

`InstallResult`

`RemoveServerResult`

Code Examples

Install a remote HTTP server

Install a stdio (npm package) server

Install a remote server with an auth header

Remove a server

List all installed servers across agents

Detect agents

Enumerate all agent types