mcp-management

MCP Server Management

Expert knowledge for managing Model Context Protocol (MCP) servers on a project-by-project basis, with support for runtime management, OAuth remote servers, and dynamic server discovery.

For server config examples, the OAuth deep-dive, dynamic-discovery detail, troubleshooting scripts, and full configuration-pattern examples, see REFERENCE.md.

When to Use This Skill

Use this skill when...	Use configure-mcp instead when...
Understanding MCP architecture and concepts	Setting up .mcp.json for a new project
Managing servers at runtime (enable/disable)	Installing new servers interactively
Setting up OAuth remote MCP servers	Running compliance checks on MCP configuration
Troubleshooting connection failures	Adding specific servers from the registry
Implementing list_changed dynamic discovery	Generating project standards reports

MCP Architecture Overview

MCP connects Claude Code to external tools and data sources via two transport types:

Transport	Usage	Auth	Configuration
Stdio (local)	Command-based servers via npx, bunx, uvx, go run	None needed	.mcp.json
HTTP+SSE (remote)	URL-based servers hosted externally	OAuth 2.1	.mcp.json with url field

Local servers declare a command + args; remote servers declare a url + headers (with ${VAR_NAME} token references, never hardcoded). See REFERENCE.md → Server configuration examples.

Runtime Server Management

/mcp Commands (Claude Code 2.1.50+)

Manage servers without editing configuration files:

Command	Description
/mcp	List all configured MCP servers and their connection status
/mcp enable <server>	Enable a server for the current session
/mcp disable <server>	Disable a server for the current session (session-scoped only)

Note: Enable/disable are session-scoped. Edit .mcp.json for permanent changes.

Check Server Status

jq -r '.mcpServers | keys[]' .mcp.json   # List configured servers
jq '.mcpServers.context7' .mcp.json      # Verify a server's config

As of 2.1.238, claude mcp list / claude mcp get report a disabled server as ⊘ Disabled immediately, without attempting to connect to it for a health check — a disabled server no longer costs a connection attempt to inspect.

OAuth Remote Servers (2.1.50+)

Remote HTTP+SSE servers use OAuth 2.1: Claude Code discovers metadata from /.well-known/oauth-authorization-server (cached per URL), the user authorizes in-browser once, and step-up auth re-prompts when a tool needs elevated scope. To refresh stale OAuth config, /mcp disable then /mcp enable the server. Full flow, step-up detail, and caching behavior in REFERENCE.md → OAuth support.

CLI Authentication (2.1.186+)

claude mcp login <server> / claude mcp logout <server> authenticate or de-authenticate a server from the command line, without opening the interactive /mcp menu. Pass --no-browser to complete the OAuth flow over SSH or another environment with no local browser.

Dynamic Tool Discovery (list_changed)

Servers declaring {"tools": {"listChanged": true}} push notifications/tools/list_changed when their tool set changes, and Claude Code refreshes that server's tools without a session restart — useful for servers exposing project-context-specific tools. Same pattern for resources and prompts. Subscription is automatic; no client config needed. See REFERENCE.md → Dynamic tool discovery.

Troubleshooting

Common failure modes and the diagnostic scripts for each (server won't connect, missing env vars, OAuth issues, client behaviors that look like server bugs, the SDK MCP race condition) are in REFERENCE.md → Troubleshooting scripts. Quick OAuth triage:

Symptom	Likely Cause	Action
Authorization prompt repeats	Token not persisted	Check token storage permissions
Step-up auth loop	Scope mismatch	Revoke and re-authorize
Discovery fails	Server down or URL wrong	Verify server URL and connectivity — claude mcp list / /mcp show the HTTP status and error text for a failed connection (2.1.219+), and warn when a config value has hidden leading or trailing whitespace; check both before assuming the URL itself is wrong. In headless/-p runs, mcp_server_errors in the stream-json init event lists any --mcp-config entries skipped by validation
Cache stale	Server changed OAuth config	Disable/enable server to refresh
Tool call hangs	Long-running MCP tool call	A call running longer than 2 minutes now moves to the background automatically so the session stays usable (2.1.212+); tune or disable with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS
Remote tool call never returns	Server stopped responding mid-call	A remote MCP tool call with no response for 5 minutes now aborts with an error instead of blocking indefinitely (2.1.187+); override with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT
0 tools / no response in a manual stdio test	stdin EOF before the reply — a burst printf … | server pipe closes input and the server exits before it answers	Hold stdin open until every response arrives — REFERENCE.md → Smoke-testing a stdio server by hand
Server still runs its old args or profile after .mcp.json changed mid-session (a git pull, an edit)	A stdio server keeps the argv it was spawned with; nothing re-reads the edited file into a running process	Compare the running argv against the file: ps -Ao lstart,command | grep '[s]erver-name' — a start time before the file's mtime (stat -f %Sm .mcp.json on macOS, stat -c %y .mcp.json on Linux) is the confirmation. Restart Claude Code (claude --continue), then confirm through the server's own self-report (a version/info tool), not the config file

MCP diagnostic output never prints resolved secrets (2.1.234+): a scope-conflict warning shows the configured ${VAR} placeholder, and a connection-failure message shows only the server origin — safe to paste into an issue or share with a teammate.

Stale cached git source

A server registered from a git URL rather than a published package serves a cached commit, so an upstream fix never arrives:

"my-server": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/<owner>/<repo>.git", "<pkg>"]
}

uvx resolves the ref to a commit once, builds it, and caches by that commit. Later spawns reuse the build and do not re-fetch the branch head. So after a fix merges to the server's main, every client keeps running the old code — and the symptom is misattributed: you restart the client, the bug persists, and you suspect the fix, the registration, or the environment.

Confirm by comparing the cached checkout's commit against upstream:

fd -H '<a-file-from-the-repo>' "$(uv cache dir)/git-v0/checkouts"   # .../<hash>/<commit>/...
git ls-remote https://github.com/<owner>/<repo>.git refs/heads/main

A cached <commit> that is not the current head is the confirmation.

Fix — refresh, then restart the client so it re-spawns from the new build:

uvx --refresh --from git+https://github.com/<owner>/<repo>.git <pkg> </dev/null

</dev/null feeds EOF so a stdio server exits after building instead of hanging for requests; the rebuild happens during resolve, so the cache is warm even if the process is then killed.

Durable fix — publish and pin. This footgun exists only for an unpinned git source. Once the server is on PyPI, register it as uvx <pkg> (or uvx <pkg>@<version>): a version bump re-resolves cleanly and there is no cached-head-went-stale failure at all. Prefer the git+ form only as an interim before the first publish. PAL now ships on PyPI, and the repo baseline policy registers it as uvx pal-mcp-server@latest (configure-plugin/policy/repo-baseline.json, mcpServers).

Configuration Patterns

Three scopes, each with a worked .mcp.json / settings.json / plugin.json example in REFERENCE.md → Configuration patterns:

• Project-scoped (recommended) — .mcp.json at project root; .gitignore it for personal configs or track for team configs.
• User-scoped (personal) — ~/.claude/settings.json for servers available everywhere.
• Plugin-scoped — declared in plugin.json (or referenced via "mcpServers": "./.mcp.json").

Post-add approval gate (project-scoped)

A newly-added project .mcp.json server requires one-time user approval before its tools are callable in the current session — this is expected, not an error. Immediately after writing the config, claude mcp list shows the server as ⏸ Pending approval (run 'claude' to approve) and it stays uncallable until the user approves it via the /mcp command or restarts the CLI session — both user-only actions the agent cannot perform for them. So after writing a project .mcp.json entry, tell the user proactively that a one-time approval (/mcp or a session restart) is needed for the new server's tools to become available, rather than discovering the gate via a status check and asking mid-flow.

Under pi

pi has no MCP client; pi install npm:pi-mcp-adapter adds one that reads this .mcp.json through a single mcp proxy tool. /mcp disable then persists, user-scoped servers need /mcp setup, and no approval gate is documented: docs/pi-export.md § MCP servers.

Agentic Optimizations

Context	Command
Quick status check	jq -c '.mcpServers | keys' .mcp.json 2>/dev/null
Validate JSON	jq empty .mcp.json 2>&1
List env vars needed	jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json 2>/dev/null | sort -u
Check specific server	jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed"
Find servers in plugin	find . -name '.mcp.json' -maxdepth 2

Quick Reference

Server Types by Transport

Type	When to Use	Example
command (stdio)	Local tools, no auth needed	bunx, npx, uvx, go run
url (HTTP+SSE)	Remote hosted servers, OAuth needed	https://...

Key Files

File	Purpose
.mcp.json	Project-level MCP server config (team-shareable)
~/.claude/settings.json	User-level MCP server config (personal)
plugin.json	Plugin-level MCP server declarations