agent-mcp-manager-v0.0.1

First public release of agent-mcp-manager: a TypeScript library for programmatically registering Model Context Protocol servers across AI coding agents (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Zed). Built for hosts (IDE plugins, internal tools, enterprise onboarding flows, custom installers) that need to wire MCP servers into a user's agent configs without shelling out to a per-agent CLI.

Alpha software. The public API may change between minor versions without notice until 1.0.0. Pin exact versions; expect rough edges.

Install

npm install agent-mcp-manager

Quick start

import { createMcpManager, detectInstalledAgents } from 'agent-mcp-manager'

const mgr = createMcpManager()

await mgr.add({
  name: 'filesystem',
  spec: {
    transport: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
  },
})

const agents = await detectInstalledAgents()
for (const a of agents.filter((a) => a.installed)) {
  await mgr.link({ serverName: 'filesystem', agent: a.id })
}

// Later, full teardown across every linked agent:
await mgr.remove({ serverName: 'filesystem' })

Mental model

Two layers, clear split of responsibility:

• Workspace (yours): a directory you own with a manifest.json recording every server you've added, its spec, when, and which agents you've linked it to. add() writes here; listServers() reads it.
• Agent MCP configs (the user's): ~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml, etc. link() injects entries into them; unlink() removes them; listLinks() reports the ones the manifest knows about. Foreign keys at those paths are never touched.

The manifest is authoritative for intent and metadata; the on-disk config files are authoritative for current state. rescan() cross-checks the two and reports verified / broken / unmanaged entries.

What's in 0.0.1

Seven primitives

add({ name, spec })
link({ serverName, agent, configPath? })
unlink({ serverName, agent, configPath? })
remove({ serverName, unlinkFirst? })
listServers({ scanUnmanaged? })
listLinks({ agents?, serverNames?, scanUnmanaged? })
rescan({ mode?: 'merge' | 'replace' })

Detection helpers

detectInstalledAgents()
listSupportedAgents()
isAgentSupported(agent)
resolveAgentMcpConfigPath(agent, scope?, projectRoot?)

Supported agents

Agent	System config (macOS)	Emitter	Project file
claude-code	~/.claude.json	JSON mcpServers	.mcp.json
claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json	JSONC mcpServers	n/a
cursor	~/.cursor/mcp.json	JSON mcpServers	.cursor/mcp.json
vscode	~/Library/Application Support/Code/User/mcp.json	JSON servers (injects type: stdio)	.vscode/mcp.json
gemini	~/.gemini/settings.json	JSON mcpServers	n/a
codex	~/.codex/config.toml	TOML mcp_servers	n/a
zed	~/.config/zed/settings.json	JSON context_servers (injects source: custom, enabled: true)	n/a

More agents (Cline, Continue.dev, OpenCode, Goose, Crush, LMStudio, Kiro, Sema4) are planned for v0.2.

Transports

• stdio is fully supported.
• sse and http types are exported and the JSON emitters write them correctly, but v0.1 tests skip non-stdio link flows. Treat as preview. Codex stays stdio-only because its upstream TOML config is stdio-only.

How this relates to docker/mcp-gateway

agent-mcp-manager derives its agent catalog from docker/mcp-gateway's pkg/client/config.yml (MIT-licensed). The per-OS paths, install-check heuristics, and config-file shapes mirror the upstream entries. Key differences:

• TypeScript-native emitters instead of yq expressions. JSONC clients use jsonc-parser; Codex uses @iarna/toml. JSONC comment preservation is built in.
• General-purpose, not Docker-specific. Docker's CLI plugin writes a single fixed MCP_DOCKER entry pointing at its gateway. This library writes arbitrary MCP server entries from caller-supplied specs.
• Manifest-backed: a manifest.json records which entries the library wrote so unlink() can refuse to clobber user-owned keys.

See THIRD_PARTY_NOTICES.md for upstream attribution.

Errors

Every error subclasses McpManagerError:

Error	When
AgentNotSupportedError	Unknown agent id
ServerNotFoundError	Operation on a server name absent from the manifest
ForeignEntryError	unlink sees an entry the manifest didn't write
InvalidServerSpecError	Spec fails validation (e.g. http transport with no url)
UnresolvedConfigPathError	OS or env vars do not yield a valid config path

Secrets

The manifest stores the server spec verbatim, including any env / headers values you pass. If your spec carries a token, the manifest holds it in plaintext at ${workspaceDir}/manifest.json. v0.2 will add optional OS-keyring indirection via keytar. For v0.1: keep your workspace dir scoped to a single user and treat manifest.json like any other secret-bearing config file.

Library, not a CLI

If you want to register a single MCP server in one of your editors interactively, use that editor's own command (claude mcp add …, the Cursor settings UI, etc.) or docker mcp client connect. This package is a programmatic API for embedders.

Links

• npm: https://www.npmjs.com/package/agent-mcp-manager
• README: https://github.com/DaniAkash/acpx/tree/main/packages/agent-mcp-manager
• MCP spec: https://modelcontextprotocol.io