mcp-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

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.

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:

| 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 | | Cache stale | Server changed OAuth config | Disable/enable server to refresh |

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.

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 |