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

MCP Architecture Overview

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

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:

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, the SDK MCP race condition) are in REFERENCE.md → Troubleshooting scripts. Quick OAuth triage:

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:

"pal": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/owner/repo.git", "pal-mcp-server"]
}

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.

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

Quick Reference

Server Types by Transport

Key Files