[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C5BPAK3316HW7MZRT503ZE":3,"skill-same:01M6C5BPAK3316HW7MZRT503ZE":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":55,"commitSha":56,"skillDirectory":57,"forksCount":58,"repositoryHtmlUrl":59,"repositoryHomepageUrl":6,"ownerHtmlUrl":60,"ownerBlogUrl":6,"ownerDescription":61,"updatedAt":62,"install":63,"resources":76},"01M6C5BPAK3316HW7MZRT503ZE","mcp-management",null,"Install, configure and troubleshoot MCP servers. Use when adding\u002Fenabling servers, editing .mcp.json, fixing OAuth, or when a server runs stale code after an upstream fix.","laurigates\u002Fclaude-plugins","laurigates","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F13014001?v=4","01M6C59YHWS9C7KMXKSRX1YXNP","Lauri Gates","01M6C59YP2APG9YAM4DWYQYGFJ",59,"MIT","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fagent-patterns-plugin\u002Fskills\u002Fmcp-management\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"mcp management","management","MCP","2026","when","upstream","sep","wed","false","2025","install","troubleshoot","edit","write","read","server","code","Bash","configure","use","fix","editing","2026-11-10 10:12:30",false,"---\ncreated: 2025-12-16\nmodified: 2026-11-02\nreviewed: 2026-09-16\nname: mcp-management\ndescription: Install, configure and troubleshoot MCP servers. Use when adding\u002Fenabling servers, editing .mcp.json, fixing OAuth, or when a server runs stale code after an upstream fix.\nuser-invocable: false\nallowed-tools: Bash(jq *), Bash(find *), Read, Write, Edit, Grep, Glob, AskUserQuestion\n---\n\n# MCP Server Management\n\nExpert 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.\n\nFor server config examples, the OAuth deep-dive, dynamic-discovery detail,\ntroubleshooting scripts, and full configuration-pattern examples, see\n[REFERENCE.md](REFERENCE.md).\n\n## When to Use This Skill\n\n| Use this skill when... | Use configure-mcp instead when... |\n|------------------------|------------------------------------|\n| Understanding MCP architecture and concepts | Setting up `.mcp.json` for a new project |\n| Managing servers at runtime (enable\u002Fdisable) | Installing new servers interactively |\n| Setting up OAuth remote MCP servers | Running compliance checks on MCP configuration |\n| Troubleshooting connection failures | Adding specific servers from the registry |\n| Implementing `list_changed` dynamic discovery | Generating project standards reports |\n\n## MCP Architecture Overview\n\nMCP connects Claude Code to external tools and data sources via two transport types:\n\n| Transport | Usage | Auth | Configuration |\n|-----------|-------|------|---------------|\n| **Stdio** (local) | Command-based servers via `npx`, `bunx`, `uvx`, `go run` | None needed | `.mcp.json` |\n| **HTTP+SSE** (remote) | URL-based servers hosted externally | OAuth 2.1 | `.mcp.json` with `url` field |\n\nLocal servers declare a `command` + `args`; remote servers declare a `url` +\n`headers` (with `${VAR_NAME}` token references, never hardcoded). See\n[REFERENCE.md → Server configuration examples](REFERENCE.md#server-configuration-examples).\n\n## Runtime Server Management\n\n### `\u002Fmcp` Commands (Claude Code 2.1.50+)\n\nManage servers without editing configuration files:\n\n| Command | Description |\n|---------|-------------|\n| `\u002Fmcp` | List all configured MCP servers and their connection status |\n| `\u002Fmcp enable \u003Cserver>` | Enable a server for the current session |\n| `\u002Fmcp disable \u003Cserver>` | Disable a server for the current session (session-scoped only) |\n\n**Note**: Enable\u002Fdisable are session-scoped. Edit `.mcp.json` for permanent changes.\n\n### Check Server Status\n\n```bash\njq -r '.mcpServers | keys[]' .mcp.json   # List configured servers\njq '.mcpServers.context7' .mcp.json      # Verify a server's config\n```\n\nAs of 2.1.238, `claude mcp list` \u002F `claude mcp get` report a disabled server as\n`⊘ Disabled` immediately, without attempting to connect to it for a health\ncheck — a disabled server no longer costs a connection attempt to inspect.\n\n## OAuth Remote Servers (2.1.50+)\n\nRemote HTTP+SSE servers use OAuth 2.1: Claude Code discovers metadata from\n`\u002F.well-known\u002Foauth-authorization-server` (cached per URL), the user authorizes\nin-browser once, and **step-up auth** re-prompts when a tool needs elevated\nscope. To refresh stale OAuth config, `\u002Fmcp disable` then `\u002Fmcp enable` the\nserver. Full flow, step-up detail, and caching behavior in\n[REFERENCE.md → OAuth support](REFERENCE.md#oauth-support-for-remote-mcp-servers).\n\n### CLI Authentication (2.1.186+)\n\n`claude mcp login \u003Cserver>` \u002F `claude mcp logout \u003Cserver>` authenticate or\nde-authenticate a server from the command line, without opening the\ninteractive `\u002Fmcp` menu. Pass `--no-browser` to complete the OAuth flow over\nSSH or another environment with no local browser.\n\n## Dynamic Tool Discovery (`list_changed`)\n\nServers declaring `{\"tools\": {\"listChanged\": true}}` push\n`notifications\u002Ftools\u002Flist_changed` when their tool set changes, and Claude Code\nrefreshes that server's tools **without a session restart** — useful for servers\nexposing project-context-specific tools. Same pattern for `resources` and\n`prompts`. Subscription is automatic; no client config needed. See\n[REFERENCE.md → Dynamic tool discovery](REFERENCE.md#dynamic-tool-discovery-list_changed).\n\n## Troubleshooting\n\nCommon failure modes and the diagnostic scripts for each (server won't connect,\nmissing env vars, OAuth issues, client behaviors that look like server bugs,\nthe SDK MCP race condition) are in\n[REFERENCE.md → Troubleshooting scripts](REFERENCE.md#troubleshooting-scripts).\nQuick OAuth triage:\n\n| Symptom | Likely Cause | Action |\n|---------|-------------|--------|\n| Authorization prompt repeats | Token not persisted | Check token storage permissions |\n| Step-up auth loop | Scope mismatch | Revoke and re-authorize |\n| Discovery fails | Server down or URL wrong | Verify server URL and connectivity — `claude mcp list` \u002F `\u002Fmcp` 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\u002F`-p` runs, `mcp_server_errors` in the stream-json init event lists any `--mcp-config` entries skipped by validation |\n| Cache stale | Server changed OAuth config | Disable\u002Fenable server to refresh |\n| 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` |\n| 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` |\n| 0 tools \u002F 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](REFERENCE.md#smoke-testing-a-stdio-server-by-hand) |\n| 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\u002Finfo tool), not the config file |\n\nMCP diagnostic output never prints resolved secrets (2.1.234+): a scope-conflict\nwarning shows the configured `${VAR}` placeholder, and a connection-failure\nmessage shows only the server origin — safe to paste into an issue or share\nwith a teammate.\n\n## Stale cached git source\n\nA server registered from a **git URL** rather than a published package serves a\n**cached commit**, so an upstream fix never arrives:\n\n```jsonc\n\"my-server\": {\n  \"command\": \"uvx\",\n  \"args\": [\"--from\", \"git+https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git\", \"\u003Cpkg>\"]\n}\n```\n\n`uvx` resolves the ref to a commit **once**, builds it, and caches by that\ncommit. Later spawns reuse the build and do **not** re-fetch the branch head. So\nafter a fix merges to the server's `main`, every client keeps running the old\ncode — and the symptom is misattributed: you restart the client, the bug\npersists, and you suspect the fix, the registration, or the environment.\n\n**Confirm** by comparing the cached checkout's commit against upstream:\n\n```sh\nfd -H '\u003Ca-file-from-the-repo>' \"$(uv cache dir)\u002Fgit-v0\u002Fcheckouts\"   # ...\u002F\u003Chash>\u002F\u003Ccommit>\u002F...\ngit ls-remote https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git refs\u002Fheads\u002Fmain\n```\n\nA cached `\u003Ccommit>` that is not the current head is the confirmation.\n\n**Fix** — refresh, then restart the client so it re-spawns from the new build:\n\n```sh\nuvx --refresh --from git+https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git \u003Cpkg> \u003C\u002Fdev\u002Fnull\n```\n\n`\u003C\u002Fdev\u002Fnull` feeds EOF so a **stdio** server exits after building instead of\nhanging for requests; the rebuild happens during resolve, so the cache is warm\neven if the process is then killed.\n\n**Durable fix — publish and pin.** This footgun exists *only* for an unpinned\ngit source. Once the server is on PyPI, register it as `uvx \u003Cpkg>` (or\n`uvx \u003Cpkg>@\u003Cversion>`): a version bump re-resolves cleanly and there is no\ncached-head-went-stale failure at all. Prefer the `git+` form only as an interim\nbefore the first publish. PAL now ships on PyPI, and the repo baseline policy\nregisters it as `uvx pal-mcp-server@latest`\n([`configure-plugin\u002Fpolicy\u002Frepo-baseline.json`](https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fconfigure-plugin\u002Fpolicy\u002Frepo-baseline.json),\n`mcpServers`).\n\n## Configuration Patterns\n\nThree scopes, each with a worked `.mcp.json` \u002F `settings.json` \u002F `plugin.json`\nexample in [REFERENCE.md → Configuration patterns](REFERENCE.md#configuration-patterns):\n\n- **Project-scoped** (recommended) — `.mcp.json` at project root; `.gitignore` it for personal configs or track for team configs.\n- **User-scoped** (personal) — `~\u002F.claude\u002Fsettings.json` for servers available everywhere.\n- **Plugin-scoped** — declared in `plugin.json` (or referenced via `\"mcpServers\": \".\u002F.mcp.json\"`).\n\n### Post-add approval gate (project-scoped)\n\nA **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 `\u002Fmcp` 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 (`\u002Fmcp` 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.\n\n### Under pi\n\npi has no MCP client; `pi install npm:pi-mcp-adapter` adds one that reads this `.mcp.json` through a single `mcp` proxy tool. `\u002Fmcp disable` then persists, user-scoped servers need `\u002Fmcp setup`, and no approval gate is documented: [docs\u002Fpi-export.md § MCP servers](https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fpi-export.md#mcp-servers-pi-mcp-adapter).\n\n## Agentic Optimizations\n\n| Context | Command |\n|---------|---------|\n| Quick status check | `jq -c '.mcpServers \\| keys' .mcp.json 2>\u002Fdev\u002Fnull` |\n| Validate JSON | `jq empty .mcp.json 2>&1` |\n| List env vars needed | `jq -r '.mcpServers[] \\| .env \u002F\u002F {} \\| keys[]' .mcp.json 2>\u002Fdev\u002Fnull \\| sort -u` |\n| Check specific server | `jq -e '.mcpServers.context7' .mcp.json >\u002Fdev\u002Fnull 2>&1 && echo \"installed\"` |\n| Find servers in plugin | `find . -name '.mcp.json' -maxdepth 2` |\n\n## Quick Reference\n\n### Server Types by Transport\n\n| Type | When to Use | Example |\n|------|-------------|---------|\n| `command` (stdio) | Local tools, no auth needed | `bunx`, `npx`, `uvx`, `go run` |\n| `url` (HTTP+SSE) | Remote hosted servers, OAuth needed | `https:\u002F\u002F...` |\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `.mcp.json` | Project-level MCP server config (team-shareable) |\n| `~\u002F.claude\u002Fsettings.json` | User-level MCP server config (personal) |\n| `plugin.json` | Plugin-level MCP server declarations |\n","# MCP Server Management\n\nExpert 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.\n\nFor server config examples, the OAuth deep-dive, dynamic-discovery detail,\ntroubleshooting scripts, and full configuration-pattern examples, see\n[REFERENCE.md](REFERENCE.md).\n\n## When to Use This Skill\n\n| Use this skill when... | Use configure-mcp instead when... |\n|------------------------|------------------------------------|\n| Understanding MCP architecture and concepts | Setting up `.mcp.json` for a new project |\n| Managing servers at runtime (enable\u002Fdisable) | Installing new servers interactively |\n| Setting up OAuth remote MCP servers | Running compliance checks on MCP configuration |\n| Troubleshooting connection failures | Adding specific servers from the registry |\n| Implementing `list_changed` dynamic discovery | Generating project standards reports |\n\n## MCP Architecture Overview\n\nMCP connects Claude Code to external tools and data sources via two transport types:\n\n| Transport | Usage | Auth | Configuration |\n|-----------|-------|------|---------------|\n| **Stdio** (local) | Command-based servers via `npx`, `bunx`, `uvx`, `go run` | None needed | `.mcp.json` |\n| **HTTP+SSE** (remote) | URL-based servers hosted externally | OAuth 2.1 | `.mcp.json` with `url` field |\n\nLocal servers declare a `command` + `args`; remote servers declare a `url` +\n`headers` (with `${VAR_NAME}` token references, never hardcoded). See\n[REFERENCE.md → Server configuration examples](REFERENCE.md#server-configuration-examples).\n\n## Runtime Server Management\n\n### `\u002Fmcp` Commands (Claude Code 2.1.50+)\n\nManage servers without editing configuration files:\n\n| Command | Description |\n|---------|-------------|\n| `\u002Fmcp` | List all configured MCP servers and their connection status |\n| `\u002Fmcp enable \u003Cserver>` | Enable a server for the current session |\n| `\u002Fmcp disable \u003Cserver>` | Disable a server for the current session (session-scoped only) |\n\n**Note**: Enable\u002Fdisable are session-scoped. Edit `.mcp.json` for permanent changes.\n\n### Check Server Status\n\n```bash\njq -r '.mcpServers | keys[]' .mcp.json   # List configured servers\njq '.mcpServers.context7' .mcp.json      # Verify a server's config\n```\n\nAs of 2.1.238, `claude mcp list` \u002F `claude mcp get` report a disabled server as\n`⊘ Disabled` immediately, without attempting to connect to it for a health\ncheck — a disabled server no longer costs a connection attempt to inspect.\n\n## OAuth Remote Servers (2.1.50+)\n\nRemote HTTP+SSE servers use OAuth 2.1: Claude Code discovers metadata from\n`\u002F.well-known\u002Foauth-authorization-server` (cached per URL), the user authorizes\nin-browser once, and **step-up auth** re-prompts when a tool needs elevated\nscope. To refresh stale OAuth config, `\u002Fmcp disable` then `\u002Fmcp enable` the\nserver. Full flow, step-up detail, and caching behavior in\n[REFERENCE.md → OAuth support](REFERENCE.md#oauth-support-for-remote-mcp-servers).\n\n### CLI Authentication (2.1.186+)\n\n`claude mcp login \u003Cserver>` \u002F `claude mcp logout \u003Cserver>` authenticate or\nde-authenticate a server from the command line, without opening the\ninteractive `\u002Fmcp` menu. Pass `--no-browser` to complete the OAuth flow over\nSSH or another environment with no local browser.\n\n## Dynamic Tool Discovery (`list_changed`)\n\nServers declaring `{\"tools\": {\"listChanged\": true}}` push\n`notifications\u002Ftools\u002Flist_changed` when their tool set changes, and Claude Code\nrefreshes that server's tools **without a session restart** — useful for servers\nexposing project-context-specific tools. Same pattern for `resources` and\n`prompts`. Subscription is automatic; no client config needed. See\n[REFERENCE.md → Dynamic tool discovery](REFERENCE.md#dynamic-tool-discovery-list_changed).\n\n## Troubleshooting\n\nCommon failure modes and the diagnostic scripts for each (server won't connect,\nmissing env vars, OAuth issues, client behaviors that look like server bugs,\nthe SDK MCP race condition) are in\n[REFERENCE.md → Troubleshooting scripts](REFERENCE.md#troubleshooting-scripts).\nQuick OAuth triage:\n\n| Symptom | Likely Cause | Action |\n|---------|-------------|--------|\n| Authorization prompt repeats | Token not persisted | Check token storage permissions |\n| Step-up auth loop | Scope mismatch | Revoke and re-authorize |\n| Discovery fails | Server down or URL wrong | Verify server URL and connectivity — `claude mcp list` \u002F `\u002Fmcp` 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\u002F`-p` runs, `mcp_server_errors` in the stream-json init event lists any `--mcp-config` entries skipped by validation |\n| Cache stale | Server changed OAuth config | Disable\u002Fenable server to refresh |\n| 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` |\n| 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` |\n| 0 tools \u002F 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](REFERENCE.md#smoke-testing-a-stdio-server-by-hand) |\n| 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\u002Finfo tool), not the config file |\n\nMCP diagnostic output never prints resolved secrets (2.1.234+): a scope-conflict\nwarning shows the configured `${VAR}` placeholder, and a connection-failure\nmessage shows only the server origin — safe to paste into an issue or share\nwith a teammate.\n\n## Stale cached git source\n\nA server registered from a **git URL** rather than a published package serves a\n**cached commit**, so an upstream fix never arrives:\n\n```jsonc\n\"my-server\": {\n  \"command\": \"uvx\",\n  \"args\": [\"--from\", \"git+https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git\", \"\u003Cpkg>\"]\n}\n```\n\n`uvx` resolves the ref to a commit **once**, builds it, and caches by that\ncommit. Later spawns reuse the build and do **not** re-fetch the branch head. So\nafter a fix merges to the server's `main`, every client keeps running the old\ncode — and the symptom is misattributed: you restart the client, the bug\npersists, and you suspect the fix, the registration, or the environment.\n\n**Confirm** by comparing the cached checkout's commit against upstream:\n\n```sh\nfd -H '\u003Ca-file-from-the-repo>' \"$(uv cache dir)\u002Fgit-v0\u002Fcheckouts\"   # ...\u002F\u003Chash>\u002F\u003Ccommit>\u002F...\ngit ls-remote https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git refs\u002Fheads\u002Fmain\n```\n\nA cached `\u003Ccommit>` that is not the current head is the confirmation.\n\n**Fix** — refresh, then restart the client so it re-spawns from the new build:\n\n```sh\nuvx --refresh --from git+https:\u002F\u002Fgithub.com\u002F\u003Cowner>\u002F\u003Crepo>.git \u003Cpkg> \u003C\u002Fdev\u002Fnull\n```\n\n`\u003C\u002Fdev\u002Fnull` feeds EOF so a **stdio** server exits after building instead of\nhanging for requests; the rebuild happens during resolve, so the cache is warm\neven if the process is then killed.\n\n**Durable fix — publish and pin.** This footgun exists *only* for an unpinned\ngit source. Once the server is on PyPI, register it as `uvx \u003Cpkg>` (or\n`uvx \u003Cpkg>@\u003Cversion>`): a version bump re-resolves cleanly and there is no\ncached-head-went-stale failure at all. Prefer the `git+` form only as an interim\nbefore the first publish. PAL now ships on PyPI, and the repo baseline policy\nregisters it as `uvx pal-mcp-server@latest`\n([`configure-plugin\u002Fpolicy\u002Frepo-baseline.json`](https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fconfigure-plugin\u002Fpolicy\u002Frepo-baseline.json),\n`mcpServers`).\n\n## Configuration Patterns\n\nThree scopes, each with a worked `.mcp.json` \u002F `settings.json` \u002F `plugin.json`\nexample in [REFERENCE.md → Configuration patterns](REFERENCE.md#configuration-patterns):\n\n- **Project-scoped** (recommended) — `.mcp.json` at project root; `.gitignore` it for personal configs or track for team configs.\n- **User-scoped** (personal) — `~\u002F.claude\u002Fsettings.json` for servers available everywhere.\n- **Plugin-scoped** — declared in `plugin.json` (or referenced via `\"mcpServers\": \".\u002F.mcp.json\"`).\n\n### Post-add approval gate (project-scoped)\n\nA **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 `\u002Fmcp` 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 (`\u002Fmcp` 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.\n\n### Under pi\n\npi has no MCP client; `pi install npm:pi-mcp-adapter` adds one that reads this `.mcp.json` through a single `mcp` proxy tool. `\u002Fmcp disable` then persists, user-scoped servers need `\u002Fmcp setup`, and no approval gate is documented: [docs\u002Fpi-export.md § MCP servers](https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fpi-export.md#mcp-servers-pi-mcp-adapter).\n\n## Agentic Optimizations\n\n| Context | Command |\n|---------|---------|\n| Quick status check | `jq -c '.mcpServers \\| keys' .mcp.json 2>\u002Fdev\u002Fnull` |\n| Validate JSON | `jq empty .mcp.json 2>&1` |\n| List env vars needed | `jq -r '.mcpServers[] \\| .env \u002F\u002F {} \\| keys[]' .mcp.json 2>\u002Fdev\u002Fnull \\| sort -u` |\n| Check specific server | `jq -e '.mcpServers.context7' .mcp.json >\u002Fdev\u002Fnull 2>&1 && echo \"installed\"` |\n| Find servers in plugin | `find . -name '.mcp.json' -maxdepth 2` |\n\n## Quick Reference\n\n### Server Types by Transport\n\n| Type | When to Use | Example |\n|------|-------------|---------|\n| `command` (stdio) | Local tools, no auth needed | `bunx`, `npx`, `uvx`, `go run` |\n| `url` (HTTP+SSE) | Remote hosted servers, OAuth needed | `https:\u002F\u002F...` |\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `.mcp.json` | Project-level MCP server config (team-shareable) |\n| `~\u002F.claude\u002Fsettings.json` | User-level MCP server config (personal) |\n| `plugin.json` | Plugin-level MCP server declarations |\n",{"name":5,"created":51,"modified":52,"reviewed":53,"description":7,"allowed-tools":54,"user-invocable":47},1765843200000,1793577600000,1789516800000,"Bash(jq *), Bash(find *), Read, Write, Edit, Grep, Glob, AskUserQuestion","main","563f16a344475a0d0d82039f26d1a16622e2d083","agent-patterns-plugin\u002Fskills\u002Fmcp-management",6,"https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins","https:\u002F\u002Fgithub.com\u002Flaurigates","Linux enthusiast, cloud engineer, neovim addict, electronics hobbyist.","2026-11-13 03:22:01",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add laurigates\u002Fclaude-plugins --skill mcp-management",{"tool":69,"command":70},"bunx","bunx skills add laurigates\u002Fclaude-plugins --skill mcp-management",{"tool":72,"command":73},"pnpm","pnpm dlx skills add laurigates\u002Fclaude-plugins --skill mcp-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fagent-patterns-plugin\u002Fskills\u002Fmcp-management\u002FSKILL.md",true,[77],{"path":78,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":81,"sourceHtmlUrl":82},"REFERENCE.md","REFERENCE","参考文档",10037,"https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fagent-patterns-plugin\u002Fskills\u002Fmcp-management\u002FREFERENCE.md",[84,109,127,143,166,196],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":93,"publishedAt":46},"01M70PFHMH9ADY0CRE6047Y4B2","kitty-show-image","Show the user an image with a note on what to judge, via a file send or a labelled kitty tab. Use when the user must see an image, or icat fails with no \u002Fdev\u002Ftty.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fkitty-plugin\u002Fskills\u002Fkitty-show-image\u002FSKILL.md",[90],{"categoryNo":91,"categoryName":92,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",[94,95,96,97,98,99,100,101,102,103,43,28,41,104,105,106,107,108,27,38],"show","kitty show image","image","kitty","show image","ls","get","send","open","dev","file","text","with","xdg","via",{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":46},"01M70PFEN18HKQ4RCQ1VPGMPTB","kitty-session-persistence","Snapshot and restore kitty terminal sessions on macOS. Use when surviving WindowServer hangs without losing tabs, configuring snapshots, or restoring after a force-reboot.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fkitty-plugin\u002Fskills\u002Fkitty-session-persistence\u002FSKILL.md",[],[97,116,117,118,32,119,28,41,120,121,122,27,38,37,36,123,124,125,126,43],"kitty session persistence","session","persistence","snapshots","uname","reboot","terminal","snapshot","macos","sessions","restore",{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":46},"01M70PFC77XGXCVQ1543VGZHYR","kitty-remote-control","Safe kitty remote control from an agent — read panes with kitty @ ls\u002Fget-text, notify, and never mutate the live terminal unasked. Use when running inside kitty.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fkitty-plugin\u002Fskills\u002Fkitty-remote-control\u002FSKILL.md",[],[134,135,97,136,137,99,138,139,100,140,141,43,28,142,41,105,106,122,27,38],"kitty remote control","remote","control","remote control","running","never","panes","notify","query",{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":149,"publishedAt":46},"01M70P6WVMCT5JG4SACTM69AF9","docs-reference-check","Dangling doc-reference gate: flag markdown naming repo paths or relative links that no longer exist. Use when docs cite moved\u002Fdeleted files, or wiring a doc-drift lint.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fdocumentation-plugin\u002Fskills\u002Fdocs-reference-check\u002FSKILL.md",[],[150,151,152,153,154,155,156,157,158,159,43,28,41,160,104,161,162,163,164,165],"docs reference check","check","reference check","reference","docs","links","python3","repo","files","auto","drift","lint","wiring","chezmoi","references","cp",{"skillNo":167,"name":168,"nameZh":6,"description":169,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":170,"categories":171,"keywords":181,"publishedAt":46},"01M6C6NDE7DAQGNWSF22J5CJ0Z","youtube-upload","Upload a video to YouTube via the Data API v3 and edit its title, description, tags or thumbnail afterwards. Use when publishing or retitling a YouTube video.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fyoutube-plugin\u002Fskills\u002Fyoutube-upload\u002FSKILL.md",[172,175,176],{"categoryNo":173,"categoryName":174,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":91,"categoryName":92,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":177,"categoryName":178,"taxonomyType":179,"taxonomyTypeDesc":180},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[182,183,184,185,156,186,38,187,36,188,189,190,43,41,104,191,192,28,193,194,195,108,27],"youtube upload","upload","youtube","Video","run","uv run","publishing","data","uv","api","v3","tags","id","title",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":203,"publishedAt":46},"01M6C6NABWW1X58KJJM4F6GQMQ","youtube-studio-share","Share a private YouTube video with a whole Google Workspace organization by scripting YouTube Studio in the browser. Use when a video must be org-only.","https:\u002F\u002Fgithub.com\u002Flaurigates\u002Fclaude-plugins\u002Fblob\u002Fmain\u002Fyoutube-plugin\u002Fskills\u002Fyoutube-studio-share\u002FSKILL.md",[202],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[204,205,206,207,184,185,208,209,210,211,212,38,213,214,215,26,43,216,28,106,217,27],"youtube studio share","share","youtube studio","studio","browser","javascript","scripting","google workspace","workspace","tool","google","only","chrome","organization"]