MCP Server Management

IMPORTANT: After adding, removing, or updating MCP servers, inform the user to restart the affected agent for changes to take effect.

CRITICAL: Before removing any server, use AskUserQuestion to confirm with the user.

Quick Reference (Claude Code)

# Install
claude mcp add --transport http <name> <url>
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add-json <name> '<json>'              # Full JSON config in one shot

# List/inspect
claude mcp list
claude mcp get <name>

# Remove (confirm with user first!)
claude mcp remove <name>

# OAuth login/logout (for OAuth-protected HTTP servers)
claude mcp login <name>
claude mcp logout <name>

Options must come BEFORE the server name. As of 2026-04, --transport http (Streamable HTTP) is recommended; sse is end-of-life.

Plugin MCP servers connect automatically at session start. Use /reload-plugins to re-init after enabling/disabling a plugin mid-session.

Multi-Agent Installation (npx add-mcp)

Install MCP servers to multiple coding agents at once using add-mcp:

# Remote server (HTTP)
npx add-mcp https://mcp.example.com/mcp

# npm package (stdio)
npx add-mcp @modelcontextprotocol/server-postgres

# Local command
npx add-mcp "npx -y @org/mcp-server --flag value"

# SSE transport
npx add-mcp https://mcp.example.com/sse --transport sse

Options

Flag	Description
-g, --global	Install globally instead of project-level
-a, --agent <agent>	Target specific agent(s), repeatable
-n, --name <name>	Custom server name
-t, --transport <type>	HTTP (default) or SSE
--header <header>	Custom HTTP headers, repeatable
-y, --yes	Skip confirmation prompts
--all	Install to all detected agents

Supported Agents

Agent	CLI Argument	Supports Project-Level
Claude Code	claude-code	Yes (.mcp.json)
Claude Desktop	claude-desktop	No (global only)
Cursor	cursor	Yes (.cursor/mcp.json)
VS Code	vscode	Yes (.vscode/mcp.json)
Gemini CLI	gemini-cli	Yes (.gemini/settings.json)
Codex	codex	Yes (.codex/config.toml, trusted projects only)
Goose	goose	No (global only)
GitHub Copilot CLI	github-copilot-cli	Yes (.vscode/mcp.json)
OpenCode	opencode	Yes (opencode.json)
Zed	zed	Yes (.zed/settings.json)

Examples

# Install to Claude Code and Cursor only
npx add-mcp -a claude-code -a cursor https://mcp.stripe.com

# Install npm package to all agents, globally
npx add-mcp -g --all @modelcontextprotocol/server-postgres

# Install with custom name and headers
npx add-mcp -n my-api --header "Authorization: Bearer TOKEN" https://api.example.com/mcp

# List available agents
npx add-mcp list-agents

See references/multi-agent.md for agent-specific config paths, formats, and transformations.

Searching for MCP Servers

When users ask to find or install an MCP server, see references/search.md for:

• Official vendor server lookup (always try first)
• MCP Registry API queries (fallback)
• Known official servers table
• User choice template format

Trust hierarchy: Official vendor > MCP reference servers > Verified partners > Community

Adding Servers (Claude Code)

With Environment Variables

The --env CLI flag is unreliable with special characters. Instead:

1. Add server without env vars:

   claude mcp add --transport stdio <name> -- npx -y @package/mcp-server
   

2. Edit config file to add env vars. See references/scopes.md for file locations.

Collect Configuration First

Before installing, check if the server needs API keys or tokens. Use AskUserQuestion to collect required values before running install commands.

Updating Servers

No direct update command exists. Options:

1. Edit config directly (preferred for credential changes)
2. Remove and re-add (confirm removal with user first)
3. Use environment variables for credentials that change often

For OAuth servers (GitHub, Sentry): Run /mcp in Claude Code to re-authenticate.

Removing Servers

Always confirm with user via AskUserQuestion before removing.

claude mcp remove <server-name>

For project-scoped servers in .mcp.json, delete the entry from the file after user confirmation.

OpenCode-specific notes

For OpenCode (anomalyco/opencode v1.14.x):

• Top-level key is mcp (not mcpServers); each server must declare type: "local" or type: "remote"
• For local servers, command is a single array ["bin", "arg1", "arg2"] — there's no separate args field
• Env vars go under environment (not env)
• Per-server enabled: false disables without removing
• Use opencode mcp auth <name> / opencode mcp logout <name> for OAuth servers (e.g., GitHub)
• Plugin tool.execute.* hooks do not fire for MCP tool calls in v1.14.x — use permission rules instead

See references/opencode-mcp.md for the full OpenCode MCP reference.

Reference

• Search and known servers: references/search.md
• Multi-agent installation: references/multi-agent.md
• OpenCode MCP: references/opencode-mcp.md
• Transport types: references/transports.md
• Scopes and config files: references/scopes.md
• Troubleshooting: references/troubleshooting.md

Scopes Summary (Claude Code)

Scope	Flag	Config Location	Use Case
Local	--scope local (default)	~/.claude.json	Personal dev servers
Project	--scope project	.mcp.json	Team-shared servers
User	--scope user	~/.claude.json	Cross-project tools

Environment Variable Syntax

In config files: ${VAR} or ${VAR:-default}

Windows Note

Use cmd /c wrapper for npx:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package