Manages Model Context Protocol (MCP) servers for Claude Code projects: installs/configures .mcp.json, OAuth remotes, runtime enable/disable, troubleshooting connections.
npx claudepluginhub laurigates/claude-plugins --plugin agent-patterns-pluginThis skill is limited to using the following tools:
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.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
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.
| 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 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 |
{
"mcpServers": {
"context7": {
"command": "bunx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
{
"mcpServers": {
"my-remote-server": {
"url": "https://mcp.example.com/sse",
"headers": {
"Authorization": "Bearer ${MY_API_TOKEN}"
}
}
}
}
/mcp Commands (Claude Code 2.1.50+)Use these slash commands to 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.
# List configured servers
jq -r '.mcpServers | keys[]' .mcp.json
# Verify server config
jq '.mcpServers.context7' .mcp.json
Claude Code 2.1.50+ includes improved OAuth handling for remote MCP servers:
Remote MCP servers using HTTP+SSE transport use OAuth 2.1:
/.well-known/oauth-authorization-serverStep-up auth occurs when a tool requires elevated permissions not granted in the initial OAuth flow:
Metadata from /.well-known/oauth-authorization-server is cached per server URL. If a remote server changes its OAuth configuration, force a refresh by:
/mcp disable <server> then /mcp enable <server> in the session{
"mcpServers": {
"my-service": {
"url": "https://api.example.com/mcp/sse",
"headers": {
"Authorization": "Bearer ${MY_SERVICE_TOKEN}"
}
}
}
}
Use ${VAR_NAME} syntax for environment variable references — never hardcode tokens.
list_changed)MCP servers that support the list_changed capability can update their tool list dynamically without requiring a session restart.
{"tools": {"listChanged": true}} in its capabilities responsenotifications/tools/list_changedresources/list_changed and prompts/list_changed — same pattern appliesThe capabilities are declared by the server during initialization. Claude Code subscribes automatically when the server declares support. No client-side configuration is required.
# Verify server command is available
which bunx # or npx, uvx, go
# Test server manually
bunx -y @upstash/context7-mcp # Should start without error
# Validate JSON syntax
jq empty .mcp.json && echo "JSON is valid" || echo "JSON syntax error"
# List all env vars referenced in .mcp.json
jq -r '.mcpServers[] | .env // {} | to_entries[] | "\(.key)=\(.value)"' .mcp.json
# Check which are set
jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json | while read var; do
clean_var=$(echo "$var" | sed 's/\${//;s/}//')
[ -z "${!clean_var}" ] && echo "MISSING: $clean_var" || echo "SET: $clean_var"
done
| 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 |
When using claude-agent-sdk 0.1.39 with MCP servers, a known race condition in SDK-based MCP servers causes CLIConnectionError: ProcessTransport is not ready for writing. Workaround: use pre-computed context or static stdio servers instead of SDK MCP servers.
Store in .mcp.json at project root. Add to .gitignore for personal configs or track for team configs.
{
"mcpServers": {
"context7": {
"command": "bunx",
"args": ["-y", "@upstash/context7-mcp"]
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
For servers you want available everywhere, add to ~/.claude/settings.json:
{
"mcpServers": {
"my-personal-tool": {
"command": "npx",
"args": ["-y", "my-personal-mcp"]
}
}
}
Plugins can declare MCP servers in plugin.json:
{
"mcpServers": {
"plugin-api": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
"args": ["--port", "8080"]
}
}
}
Or via external file: "mcpServers": "./.mcp.json"
| 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 |
| 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://... |
| 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 |